InfluxElixir

Elixir client library for InfluxDB v3 with v2 compatibility.

Installation

Add influx_elixir to your list of dependencies in mix.exs:

def deps do
  [
    {:influx_elixir, "~> 0.1"}
  ]
end

Configuration

The library is an OTP application: it starts one supervisor per connection listed in config, each with its own Finch pool and (optionally) a batch writer. Hosts are bare hostnames — the scheme and port are separate options.

# config/runtime.exs
config :influx_elixir, :connections,
  default: [
    host: "localhost",
    port: 8181,
    scheme: :http,
    token: System.fetch_env!("INFLUX_TOKEN"),
    database: "my_database"
  ]

For InfluxDB 2.x add api_version: :v2 and org: "my-org" (the v2 write endpoint is bucket/org scoped). Connections can also be added at runtime with InfluxElixir.add_connection/2. See InfluxElixir.Config for every option, including batch_writer:, timeout:, pool_timeout: and flight_port:.

Usage

Every operation goes through the InfluxElixir facade and accepts either a connection name or a connection term:

point = InfluxElixir.point("cpu", %{"value" => 0.64}, tags: %{"host" => "web01"})
{:ok, :written} = InfluxElixir.write(:default, point)
# Line protocol, or a list of points, writes the same way:
{:ok, :written} = InfluxElixir.write(:default, "cpu,host=web01 value=0.64")

{:ok, rows} =
  InfluxElixir.query_sql(:default, "SELECT * FROM cpu WHERE host = $host",
    params: %{host: "web01"}
  )

# rows: [%{"host" => "web01", "value" => 0.64, "time" => ~U[...]}]

InfluxElixir.write/3 sends one request per call and encodes Points for the call's :precision and the connection's api_version. A connection started with a batch_writer: option also buffers writes: InfluxElixir.write_batched/3 returns as soon as the point (or line protocol) is buffered, and the writer sends the buffer when it holds batch_size lines, when flush_interval_ms passes, or on InfluxElixir.flush/2. Failed requests are retried with backoff when a retry can help (network errors, 5xx, 408, 429). A point without a timestamp is stamped when it is buffered, so a retry cannot store it twice at two times. sync: true waits until the payload's batch is written.

:ok = InfluxElixir.write_batched(:default, point)
:ok = InfluxElixir.write_batched(:default, "cpu value=0.5", sync: true)
:ok = InfluxElixir.flush(:default)
{:ok, %{total_writes: _, total_errors: _, total_bytes: _}} = InfluxElixir.stats(:default)

Large result sets stream with InfluxElixir.query_sql_stream/3; Arrow Flight is available with transport: :flight. Write and query operations emit [:influx_elixir, :write | :query, ...] telemetry events.

Testing

This library ships with InfluxElixir.Client.Local, an in-memory InfluxDB client that enables fast, isolated tests with async: true and no external dependencies. Configure it in config/test.exs:

config :influx_elixir, :client, InfluxElixir.Client.Local

LocalClient enforces an InfluxDB version profile matching your production backend, so your tests fail if you use operations your real InfluxDB doesn't support:

setup do
  InfluxElixir.TestHelper.setup_influx(databases: ["myapp_test"], profile: :v3_core)
end

See the Testing with LocalClient guide for full setup instructions, shared case templates, and contract testing.

Documentation

Full documentation available at HexDocs.

License

MIT — see LICENSE.