node-influx

An InfluxDB Node.js Client

- Reward the contributors for their efforts on upcoming tasks.

Installation

npm install influx

Usage

Create a client instance (database not required for all methods):

var influx = require('influx')

var client = influx({

  //cluster configuration
  hosts : [
    {
      host : 'localhost',
      port : 8060, //optional. default 8086
      protocol : 'http' //optional. default 'http'
    }
  ],
  // or single-host configuration
  host : 'localhost',
  port : 8086, // optional, default 8086
  protocol : 'http', // optional, default 'http'
  username : 'dbuser',
  password : 'f4ncyp4ass',
  database : 'my_database'
})

A list of all configuration values can be found below.

You can either pass a single hostname or an array of hostnames. Node-influx uses round-robin balancing to distribute the requests across all configured hosts. When a host is unreachable, node-influx tries to resubmit the request to another host and disables the failed host for 60 seconds (timeout value is configurable). If all servers fail to respond, node-influx raises an error.

Configuration options

Option	Description
username	username
password	password
database	database name
host	hostname, e.g. 'localhost'
port [optional]	influxdb port, default: 8086
protocol [optional]	protocol, default: http
hosts [optional]	Array of hosts for cluster configuration, e.g. [ {host: 'localhost', port : 8086},...] Port is optional
depreciatedLogging [optional]	logging function for depreciated warnings, defaults to console.log
failoverTimeout [optional]	number of ms node-influx will take a host out of the balancing after a request failed, default: 60000
requestTimeout [optional]	number of ms to wait before a request times out. defaults to 'null' (waits until connection is closed). Use with caution!
maxRetries [options]	max number of retries until a request raises an error (e.g. 'no hosts available'), default : 2
timePrecision [optional]	Time precision, default : ms

Functions

###setRequestTimeout Sets the default timeout for a request. When a request times out the host is removed from the list of available hosts and the request is resubmitted to the next configured host. The default value is null (will wait forever for a respose).

Be careful with this setting. If the value is too low, slow queries might disable all configured hosts.

setRequestTimeout( value ) { }

###setFailoverTimeout Sets the failover timeout for a host. After a host has been removed from balancing, it will be re-enabled after 60 seconds (default). You can configure the timeout value using this function.

setFailoverTimeout( value ) { }

###getHostsAvailable Returns an array of available hosts.

getHostsAvailable( ) { }

###getHostsDisabled Returns an array of disabled hosts. This can be useful to check whether a host is unresponsive or not.

getHostsDisabled( ) { }

###createDatabase Creates a new database - requires cluster admin privileges

createDatabase(databaseName, [options,] callback) { }

Options can be an array of shard spaces and/or continuous queries.

###deleteDatabase Deletes a database - requires cluster admin privileges

deleteDatabase(databaseName, callback) { }

###getDatabaseNames Returns array of database names - requires cluster admin privileges

getDatabaseNames(function(err,arrayDatabaseNames){}) { }

###getSeriesNames Returns array of series names from given database - requires database admin privileges

getSeriesNames(databaseName, function(err,arraySeriesNames){} ) { }

###getUsers Returns an array of database users - requires cluster admin privileges

getUsers(databaseName, callback) { }

###getUser Returns a database user - requires cluster admin privileges

getUser(databaseName, username, callback) { }

###createUser Creates a new database user - requires cluster admin privileges

createUser(databaseName, username, password, callback) { }

###updateUser Updates database user - requires cluster admin privileges

updateUser(databaseName, username, options, callback) { }

e.g.:
// adds database admin privilege
influxDB.updateUser('myDatabase','johndoe',{admin:true},callback);

###writePoint Writes a point to a series - requires database user privileges

var point = { attr : value, time : new Date()};
writePoint(seriesName, point, options, callback) { }

###writePoints Writes multiple points to a series - requires database user privileges

var points = [ {attr : value, time : new Date()}, {attr : value2, time : new Date()}];
writePoints(seriesName, points, options, callback) { }

###writeSeries Writes multiple point to multiple series - requires database user privileges

var points = [ {attr : value, time : new Date()}, {attr : value2, time : new Date()}];
var points2 = [ {attr : value, time : new Date()}, {attr : value2, time : new Date()}];

var series = {
    series_name_one : points,
    series_name_two : points2
};

writeSeries(series, options, callback) { }

Please note that there's a POST limit at about 2MB per request. Do not submit too many points at once.

###query Queries the database - requires database user privileges

var query = 'SELECT MEDIAN(column) FROM myseries WHERE time > now() - 24h';
query(query, callback) { }


query(query, callback) { }

###getContinuousQueries Fetches all continuous queries from a database - requires database admin privileges

getContinuousQueries( [databaseName,] callback) { }

###dropContinuousQuery Drops a continuous query from a database - requires database admin privileges

dropContinuousQuery( [databaseName,] queryID, callback) { }

###getShardSpaces Returns array of all shard spaces for a database - requires cluster admin privileges

getShardSpaces( [databaseName,] function(err, arrayShardSpaces){} ) { }

###createShardSpace Creates a new shard space for a database - requires cluster admin privileges

var shardSpace = {
    name: '30d_shard',
    retentionPolicy: '30d',
    shardDuration: '7d',
    regex: '/.*/',
    replicationFactor: 1,
    split: 1
};
createShardSpace( [databaseName,] shardSpace, callback) {}

###updateShardSpace Updates a shard space - requires cluster admin privileges

var updatedShardSpace = {
    retentionPolicy: '60d',
    shardDuration: '14d',
    regex: '/.*/',
    replicationFactory: 1,
    split: 1
};
updateShardSpace( [databaseName,] shardSpaceName, updatedShardSpace, callback) { }

###deleteShardSpace Deletes a shard space - requires cluster admin privileges

deleteShardSpace( [databaseName,] shardSpaceName, callback) { }

###dropSeries Drops a series from a database - requires database admin privileges

dropSeries ( [databaseName ,] seriesName, callback) { }

As Jeff Atwood puts it... Read the source, Luke. If you're still stuck, read the ./examples/* files and the ./test.js file.

Testing

Either install InfluxDB or use a docker container to run the service:

docker run -d -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 tutum/influxdb

Then to run the test harness use npm test.

Licence

MIT