• Stars
    star
    220
  • Rank 180,422 (Top 4 %)
  • Language
    Elixir
  • License
    Apache License 2.0
  • Created almost 10 years ago
  • Updated 9 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

InfluxDB driver for Elixir

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.1

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