InfluxElixir.Client.HTTP (InfluxElixir v0.1.21)

Copy Markdown View Source

Production InfluxDB client implementation using Finch.

Communicates with real InfluxDB v3 (and v2) instances over HTTP. Uses Finch connection pools for efficient HTTP/1.1 and HTTP/2.

Connection

The connection parameter is a keyword list containing at minimum :host, :token, :scheme, :port, and a :name atom used to resolve the Finch pool. These are typically produced by InfluxElixir.Config.validate!/1.

InfluxDB v3 API Endpoints (api_version: :v3, the default)

  • Write: POST /api/v3/write_lp?db=DATABASE&precision=PRECISION
  • SQL Query: POST /api/v3/query_sql (JSON body)
  • InfluxQL: POST /api/v3/query_influxql (JSON body)
  • Databases: GET/POST/DELETE /api/v3/configure/database
  • Tokens: POST/DELETE /api/v3/configure/token
  • Health: GET /health

InfluxDB v2 (api_version: :v2)

Set api_version: :v2 on the connection. A v2 server answers 200 to the v3 write path without storing anything, so the version must be explicit.

  • Write: POST /api/v2/write?org=ORG&bucket=DATABASE&precision=ns|us|ms|s (the connection's :org and the :database opt name the bucket)
  • Flux: POST /api/v2/query (JSON body, #datatype-annotated CSV back)
  • Buckets: GET/POST/DELETE /api/v2/buckets. create_bucket/3 resolves the org ID from the connection's :org name (override with org_id:); delete_bucket/2 accepts a bucket name or a 16-hex bucket ID.

Request Timeout

Every request uses Finch's :receive_timeout option. The value is resolved with this precedence on each call:

  1. opts[:timeout] (per-call override)
  2. connection[:timeout] (connection-level default)
  3. 30_000 ms (module default, matching InfluxElixir.Flight.Client)

Finch's own default of 15s is bypassed — most production InfluxDB v3 queries need longer. To use the Finch default, pass timeout: 15_000 explicitly. Admin callbacks that don't accept opts (list_databases, delete_database, health, etc.) use the connection-level default or fall back to 30s.

Pool Checkout Timeout

Finch also bounds how long a request waits to check a connection out of the pool (pool_timeout, Finch default 5 s). That bound applies before receive_timeout and is independent of it, so against a slow or multi-node endpoint a request can fail with a transport :timeout after 5 s no matter how large :timeout is. It resolves the same way:

  1. opts[:pool_timeout] (per-call override)
  2. connection[:pool_timeout] (connection-level default)
  3. 5_000 ms (Finch's default)

A checkout that times out is reported as {:error, {:connection_error, :pool_timeout}} (Finch itself raises in that case). The streaming query uses both timeouts as well and raises an InfluxElixir.StreamError with reason: :pool_timeout.