gruchalski.com

Erflux, InfluxDB client for Erlang

 466  3 mins

It’s been already a month since I released erflux on github. Erflux is an Erlang client for InfluxDB HTTP protocol.

§Installation

1
2
3
4

{deps, [
  {erflux, ".*",
    {git, "git://github.com/radekg/erflux.git", {tag, "version-1"}}}
}]}

and run

./rebar get-deps

§Configuration

Erflux allows configuring a number of parameters:

  • InfluxDB host, default 127.0.0.1
  • InfluxDB port, default 8086
  • username, default: root
  • password, default: root
  • SSL usage, default: false
  • timeout, default: infinity

The simplest way of applying configuration is to use application:set_env, like the example below:

application:start(crypto),
application:start(asn1),
application:start(public_key),
application:start(ssl),
application:start(idna),
application:start(hackney),
application:start(jsx),
application:load(erflux),
application:set_env(erflux, host, <<"192.168.50.115">>),
application:set_env(erflux, port, 8086),
application:set_env(erflux, username, <<"root">>),
application:set_env(erflux, password, <<"root">>),
application:set_env(erflux, ssl, false),
application:set_env(erflux, timeout, infinity),
application:start(erflux),
erflux_sup:add_erflux(erflux_http),
erflux_http:get_databases().

§Writing data

To write data with erlfux:

1
2
3
4
5
6
7

erflux_http:write_series(erfluxtest, [
  [
    { points, [ [ 1, 2, 3 ] ] },
    { name, testseries },
    { columns, [ a, b, c ] }
  ]
]).

or

1
2
3
4
5

erflux_http:write_point(erfluxtest, testseries, [
  { a, 1 },
  { b, 2 },
  { c, 3 }
]).

§Reading data

Reading many columns:

erflux_http:read_point(erfluxtest, [a, b], testseries).

or a single column:

erflux_http:read_point(erfluxtest, a, testseries).

More complex queries like this can be executed using the q function:

erflux_http:q(erfluxtest, <<"select A from testseries limit 1">>).

§Advanced features

In case if it is necessary to open multiple connection to different InfluxDB servers, erflux allows for it by instantiating multiple clients. The application has a choice of using provider supervisor:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

application:start(crypto),
application:start(asn1),
application:start(public_key),
application:start(ssl),
application:start(idna),
application:start(hackney),
application:start(jsx),
application:start(erflux),
%% This will connect to localhost, if no other settings provided:
erflux_sup:add_erflux(erflux_http),
erflux_http:get_databases().

%% Start the additional client, connect to a different host:
{ok, RemoteHost} = erflux_sup:add_erflux(erflux_custom_host, <<"root">>, <<"root">>, <<"somehost.influxdb">>).

%% To list databases of the remote host, do the following:
erflux_http:get_databases(RemoteHost).

%% To remove the instance:
erflux_sup:remove_erflux(erflux_custom_host).

or bypassing the supervisor:

1
2

{ ok, Pid } = erflux_http:start_link( erflux_custom, #erflux_config{} ),
erflux_http:get_databases( Pid ).

§Atoms and binaries

Every function comes in 2 variants:

  • accepting atoms
  • and accepting binaries

It’s not possible to mix argument types. For example, this will fail:

1

erflux_http:create_database_user(database, <<"username">>, password).

Query parameter of erflux_http:q is always binary.

The exceptions to the all rule are columns in write_series, write_point and read_series. All these are valid:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

erflux_http:write_series(erfluxtest, [
  [
    { points, [ [ 1, 2, 3 ] ] },
    { name, testseries },
    { columns, [ a, <<"b">>, c ] }
  ]
]).

erflux_http:write_point(erfluxtest, testseries, [
  { a, 1 },
  { <<"b">>, 2 },
  { c, 3 }
]).

erflux_http:read_point(erfluxtest, [<<"a">>, b], testseries).

§The code

The code is available on github. It is licensed under the MIT license.

See Also: