greptimex

# Migrating from 0.3 to 0.4

Version 0.4 changes the public API. Replace `use Greptimex.Connection` with
`use Greptimex`. The old macro is no longer available.

## Client configuration

Replace nested pool options with client options:

```elixir
# Before
use Greptimex.Connection,
  pool: [pool_size: 5, channel: [address: "localhost:4001", opts: []]],
  header: [dbname: "public"],
  defaults: [timestamp_name: "ts", timestamp_datatype: :TIMESTAMP_MICROSECOND]

# After
use Greptimex,
  address: "localhost:4001",
  pool_size: 5,
  header: [dbname: "public"],
  timestamp_name: "ts",
  timestamp_unit: :microsecond
```

The module facade still accepts `otp_app`. It reads configuration at startup,
so restart the client to apply runtime changes. The default pool size
is one, with concurrent gRPC requests per channel. The default RPC timeout is
15 seconds. Greptimex passes it to both ingestion and query stubs. There is no public
channel checkout API. Use the registered atom name with functional operations.

## Writes

```elixir
# Before
MyApp.Greptime.insert({"metrics", points})
MyApp.Greptime.insert([{"metrics", points}, {"logs", logs}])

# After
MyApp.Greptime.insert("metrics", points)
MyApp.Greptime.insert_batch([{"metrics", points}, {"logs", logs}])
# Or without defining a facade:
Greptimex.insert(MyApp.Greptime, "metrics", points)
```

The success result remains `{:ok, affected_rows}`. Replace uppercase protobuf
atoms in typed values with lowercase public atoms. For example, change
`{value, :UINT32}` to `{value, :uint32}`. Replace `defaults: [...]` call options with `timestamp_name`
and `timestamp_unit` directly. A schema may be supplied per request or table entry.

Greptimex now infers booleans as `:boolean`. It returns validation errors for
incompatible column types, integer overflow, name collisions, all-null columns
without a type and unsupported values. It no longer converts unsupported values
to strings. Reuse `Greptimex.Schema` to keep column types stable across batches.

Version 0.4 removes the old JSON, list, decimal and interval encodings. Convert
these values to a supported storage type before inserting them.

## Queries

```elixir
# Before
MyApp.Greptime.query_instant(query, time, "5m", timeout: 5_000)
MyApp.Greptime.query_range(query, first, last, "1m", "5m", timeout: 5_000)

# After
MyApp.Greptime.query_instant(query, time: time, lookback: "5m", timeout: 5_000)
MyApp.Greptime.query_range(query, first, last, "1m", lookback: "5m", timeout: 5_000)
```

Replace `{:ok, series}` matches with
`{:ok, %Greptimex.PromQL.Result{type: :vector, data: series}}`. Match `:matrix`
results the same way. Scalar and string results each contain one sample.
Results keep warnings and infos. Use `decode: :raw` for the decoded JSON envelope.

Non-finite numeric values use atoms. Greptimex preserves fractional query times.
Integer query times still count Unix seconds, while ingestion integers use the
configured timestamp unit.

## Errors and instrumentation

Replace matches on arbitrary error maps or `GRPC.RPCError` with
`%Greptimex.Error{kind: ..., code: ...}`. Invalid ingestion or query data returns
a validation error. Invalid configuration and keyword options raise `ArgumentError`. Unexpected bugs,
throws and process exits propagate to the caller, including races with shutdown.

Greptimex now supervises native gRPC connection workers and requires gRPC 1.0.5
or newer. Remove ConnGRPC-specific options and telemetry handlers.
`channel_options` configures `GRPC.Client.Connection`. Greptimex sets `name`
and `target`, so you cannot override those keys in `channel_options`.

Startup does not wait for the network. Operations return a connection error until
a channel is ready. Greptimex never resends failed requests.

Replace telemetry `:success` and `:failure` handlers with `:stop`. Check
`metadata.status` to distinguish success from a returned error. Unexpected
exceptions emit `:exception`. Duration now includes validation and decoding. Metadata omits query text and row payloads. Use the
client name to distinguish instances. `affected_rows` and normalized
`result_count` remain available on successful stop events. Old query/time/dbname
and requested row-count metadata are not emitted.