Instream

InfluxDB driver for Elixir

InfluxDB Support

Tested InfluxDB versions:

1.7.11
1.8.10
2.0.9
2.1.1
2.2.0
2.3.0
2.4.0
2.5.1
2.6.1
2.7.6

Package Setup

To use Instream with your projects, edit your mix.exs file and add the required dependencies:

defp deps do
  [
    # ...
    {:instream, "~> 2.0"},
    # ...
  ]
end

Testing

To run the tests you need to have HTTP authentication enabled.

The following environment variables are used to select some test suites and the InfluxDB version under test:

INFLUXDB_HOST: the hostname where the InfluxDB can be reached (e.g. localhost)
INFLUXDB_PORT: the port where InfluxDB receives queries on (e.g. 8086)
INFLUXDB_SCHEME: the scheme (protocol) to connect to InfluxDB with (e.g. http or https)
INFLUXDB_VERSION: the tested InfluxDB version as major.minor, e.g. "1.8", "2.0", or "2.4", use "cloud" for testing against an InfluxDB Cloud instance
INFLUXDB_V1_DATABASE: the database used for InfluxDB v1.x tests (will receive a DROP and CREATE during test start!)
INFLUXDB_V1_PASSWORD: password for the INFLUXDB_V1_USERNAME account
INFLUXDB_V1_PORT_UDP: the UDP port used for writer testing (should be configured to write to INFLUXDB_V1_DATABASE)
INFLUXDB_V1_SOCKET: path to the InfluxDB unix socket (InfluxDB 1.8 only)
INFLUXDB_V1_USERNAME: username with admin privileges for the InfluxDB test instance
INFLUXDB_V2_BUCKET: the bucket used for InfluxDB v2.x tests
INFLUXDB_V2_DATBASE: the mapped database used for testing the legacy API
INFLUXDB_V2_ORG: organization associated with the INFLUXDB_V2_BUCKET
INFLUXDB_V2_RETENTION: the retention policy associated with the INFLUXDB_V2_DATBASE
INFLUXDB_V2_TOKEN: the authentication token used

Usage

Connections

To connect to an InfluxDB server you need a connection module:

defmodule MyConnection do
  use Instream.Connection, otp_app: :my_app
end

The :otp_app name and the name of the module can be freely chosen but have to be linked to a corresponding configuration entry. This defined connection module needs to be hooked up into your supervision tree:

children = [
  # ...
  MyConnection,
  # ...
]

Example of the matching configuration entry:

# InfluxDB v2.x
config :my_app, MyConnection,
  auth: [method: :token, token: "my_token"],
  bucket: "my_default_bucket",
  org: "my_default_org",
  host: "my.influxdb.host",
  version: :v2

# InfluxDB v1.x
config :my_app, MyConnection,
  auth: [username: "my_username", password: "my_password"],
  database: "my_default_database",
  host: "my.influxdb.host"

More details on connections and configuration options can be found with the Instream.Connection and Instream.Connection.Config modules.

Queries

# Flux query
MyConnection.query(
  """
    from(bucket: "#{MyConnection.config(:bucket)}")
    |> range(start: -5m)
    |> filter(fn: (r) =>
      r._measurement == "instream_examples"
    )
    |> first()
  """
)

# InfluxQL query
MyConnection.query("SELECT * FROM instream_examples")

A more detailed documentation on queries (reading/writing/options) is available in the documentation for the modules Instream and Instream.Connection.

Series Definitions

If you do not want to define the raw maps for writing data you can pre-define a series for later usage:

defmodule MySeries do
  use Instream.Series

  series do
    measurement "my_measurement"

    tag :bar
    tag :foo

    field :value
  end
end

More information about series definitions can be found in the module documentation of Instream.Series.

Writing Series Points

You can then use this module to assemble a data point (one at a time) for writing:

data = %MySeries{}
data = %{data | fields: %{data.fields | value: 17}}
data = %{data | tags: %{data.tags | bar: "bar", foo: "foo"}}

And then write one or many at once:

MyConnection.write(point)
MyConnection.write([point_1, point_2, point_3])

License

Apache License, Version 2.0

mneudert/instream