Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mneudert/instream
InfluxDB driver for Elixir
https://github.com/mneudert/instream
Last synced: 9 days ago
JSON representation
InfluxDB driver for Elixir
- Host: GitHub
- URL: https://github.com/mneudert/instream
- Owner: mneudert
- License: apache-2.0
- Created: 2015-02-10T22:44:46.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-06-06T12:41:49.000Z (5 months ago)
- Last Synced: 2024-10-14T10:29:47.798Z (25 days ago)
- Language: Elixir
- Size: 1.8 MB
- Stars: 222
- Watchers: 6
- Forks: 36
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- freaking_awesome_elixir - Elixir - InfluxDB driver for Elixir. (Instrumenting / Monitoring)
- awesome-influxdb - instream - InfluxDB driver for Elixir (Client libraries / Unofficial)
- fucking-awesome-elixir - instream - InfluxDB driver for Elixir. (Instrumenting / Monitoring)
- awesome-elixir - instream - InfluxDB driver for Elixir. (Instrumenting / Monitoring)
README
# 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:
```elixir
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:
```elixir
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:
```elixir
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
```elixir
# 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:
```elixir
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:
```elixir
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:
```elixir
MyConnection.write(point)
MyConnection.write([point_1, point_2, point_3])
```
## License
[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)