InfluxDB is an open source time series database developed by InfluxData that runs on 64-bit Windows, macOS or the Raspberry Pi Raspbian distribution. In this tutorial we will learn how to install InfluxDB on these three systems. InfluxDB is optimized for recording events or metrics. Originally developed to monitor server activity, it is very well suited for recording events or measurements from connected objects. InfluxDB is used in industry (IBM, ebay, Cisco, Citrix …) or research centers. For example, Geneva CERN uses InfluxDB to record the data generated during the LHC experiments. It’s an excellent solution combined with Node-RED to record the measurements of your connected objects and plot fantastic graphics with Grafana.
It is also possible to install InfluxDB on most Linux distributions. InfluxDB is available for 64-bit Windows only. If you have a 32-bit version, you will have to install Docker (docker pull influxdb) or use a virtual machine. For Linux Debian or Ubuntu 16.x distributions, read this specific tutorial.
Contents
- 1 Benefits of InfluxDB for (DIY) connected objects projects
- 2 Install InfluxDB on Raspbian Stretch for Raspberry Pi
- 3 Note regarding SD cards
- 4 How to install InfluxDB on Windows
- 5 How to install InfluxDB on macOS
- 6 Terminology, difference with SQL database
- 7 Database Management Methods
- 8 Establish a retention policy
- 9 Discover the InfluxDB Shell
Benefits of InfluxDB for (DIY) connected objects projects
Traditional databases (MariaDB, MySQL for example) are designed to store and link the data in them. They are very well suited to manage customer accounts and record orders from a merchant site. There is nothing to prevent the recording of time-dependent data, but in this case you will have to manually delete the old data. Other database architectures have been devised. InfluxDB answers three objectives:
- Simplify configuration and management
- Time-dependent data recording and access engine (timestamp)
- Create rules for automatically storing and deleting outdated data
Install InfluxDB on Raspbian Stretch for Raspberry Pi
Before you can install InfluxDB on Raspbian, you need to tell the system where the keys for the InfluxDB project repository are.
curl -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add -
There are two versions of InfluxDB. The first is suitable for Debian 8.0 or higher (Raspbian Jessie or Stretch), the other for Debian 7.0 (Raspbian Wheezy)
To know the version of your system, run the command lsb_release -a
pi@raspberrypi:~ $ lsb_release -a No LSB modules are available. Distributor ID: Raspbian Description: Raspbian GNU/Linux 9.1 (stretch) Release: 9.1 Codename: stretch
I advise you to update your system (upgrade) in order to have the latest versions by executing these two commands
sudo apt-get update && apt-get upgrade
Then run these commands which will add the apt-transport-https package, add the link to the source of InfluxDB, update the system and finally install InfluxDB.
sudo apt install apt-transport-https echo "deb https://repos.influxdata.com/debian jessie stable" | sudo tee /etc/apt/sources.list.d/influxdb.list sudo apt-get update sudo apt-get install influxdb
InfluxDB is now installed. InfluxDB is already pre-configured. If you want to be able to save data from a connected object using an HTTP request or from Node-RED, you will have to allow connections from the HTTP port. To do this, simply modify the configuration file in the directory /etc/influxdb/influxdb.conf
sudo nano /etc/influxdb/influxdb.conf
We uncomment the following lines
Note regarding SD cards
The Raspberry Pi uses an SD card to operate the system and store the data. It is imperative to purchase an SD card suitable for intensive data logging. These are mostly SD cards suitable for camcorders or digital cameras. Feel free to spend a few extra euros on a fast brand name card. Opt for a minimum SDXC II card. You will find more info in this article.
How to install InfluxDB on Windows
It takes a little searching on the site of InfluxData, but there is a version for Windows. She is available for Windows 64-bit.
You can install it by downloading this page or from wget for Windows . In this case, run the following command
wget https://dl.influxdata.com/influxdb/releases/influxdb-1.1.0_linux_amd64.tar.gz tar xvfz influxdb - 1.1.0_linux_amd64.tar.gz
With no Windows 64 bit at my disposal, I have not tested on this environment.
How to install InfluxDB on macOS
macOS version tested : 10.11.6 (El Captain) on a Mac Mini 2011
InfluxDB installs on macOS using Brew . BREW is a package manager for Mac (project official page).
Open a Terminal and paste this command
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Answer the questions to complete the installation of Brew on your Mac.
Now we can install InfluxDB by running these commands
brew update brew install influxdb
To run influxDB at startup, run this command
ln -sfv /usr/local/opt/influxdb/*.plist ~/Library/LaunchAgents
Now, to start InfluxDB, run this command (accept the request of incoming connections in the window that appears)
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.influxdb.plist
Or to start manually in a Terminal
influxd -config /usr/local/etc/influxdb.conf
Check if InfluxDB works
InfluxDB exposes an API with which one can easily check its good working condition. Here’s what you will receive in return for this curl command
$ curl -sl -I localhost:8086/ping HTTP/1.1 204 No Content Content-Type: application/json Request-Id: 165b0fa4-ad88-11e6-8a6f-000000000000 X-Influxdb-Version: v1.1.0 Date: Fri, 18 Nov 2016 12:11:08 GMT
InfluxDB is properly started
Terminology, difference with SQL database
Like all non-relational database, InfluxDB for its own vocabulary you need to know before starting.
- Measurement is equivalent to SQL table
- Tags is similar to a indexed column (column) in a SQL database
- Fields is similar to the columns not indexed in a SQL database
- Points is equivalent to line (row) in a SQL database
Database Management Methods
There are 6 (CREATE database management methods DATABASE, DROP DATABASE, DROP SETS, DELETE, DROP MEASUREMENT, DROP SHARD). Here’s how work the first 2, for others, everything can be found here.
Create a database
Syntax
CREATE DATABASE <database_name> [WITH [DURATION <duration>] [REPLICATION <n>] [SHARD DURATION <shard_duration>] [NAME <retention-policy-name>]]
Basic settings
- database_name: name of the database
- duration: you can set the period of data retention (conservation) but it makes more sense to implement a retention policy (see next paragraph)
Example
CREATE DATABASE "temperatures"
Delete a database (drop database)
Syntax
DROP DATABASE <database_name>
We just the name of the base (database_name) to remove.
Establish a retention policy
InfluxDB incorporates a system of automatic deletion of data. It is the policy of Retention (Retention Policy). Spent some time, data is automatically deleted from the base. This mechanism is very convenient because it for a good grasp of the size of the base and we don’t have to worry about this maintenance operation. Free to each set the lifetime of any particular measure. If you want to follow the temperature of its microprocessor, one less may be sufficient, instead the retention policy must be more flexible if we want to compare the temperature in a House from one year to the other. It will also think about the system upstream, you don’t have to store a measurement of atmosphere temperature every 10 seconds! A measure per minute, 15 minutes, that’s enough. Instead in an industrial process, we certainly want to go for the second… or a lot less.
We therefore for 3 methods
- Create: to create a rule of conservation of data
- Alter: to change a rule
- Drop: to remove a rule
Create a retention policy
Syntax
CREATE RETENTION POLICY <name_politic_retention> ON <name_database> DURATION <duration> REPLICATION <n> [SHARD DURATION <duration_shard>] [DEFAULT]
Parameters
- name_politic_retention: a short name without spaces of preference
- name_database: the database on which applies the retention policy
- duration: duration of data retention. It’s a literal expression which must respect the convention InfluxDB ( here ).
- For example if you want to keep the data for 30 days, it will show 30 d. If you want to keep without limitation of time, it indicates INF (infinity).
- duration_shard : the duration of storage of the data in the buffer zone. Here for more info.
- n : number of replication (required), put 1 if no cluster installed
Example
> CREATE RETENTION POLICY "one_day_only" WE "NOAA_water_database" DURATION 1 d REPLICATION 1 >
This policy keeps the records during a day (one_day_only) based NOAA_water_database. The data are stored in space shard 1 day. Replication 1 indicates that a copy of each item is copied in the cluster (it takes only it cluster exists).
Modify retention policy (alter retention policy)
This method allows to change an existing retention policy.
Syntax
ALTER RETENTION POLICY <name_politic_retention> ON <nom_database> DURATION <duration> REPLICATION <n> SHARD DURATION <duration_shard> DEFAULT
Parameters
- name_politic_retention: the name of the policy to change
- name_database: database on which it applies
- duration , duration_shard : see above
- n : number of replication (required), put 1 if no cluster installed
Example
> ALTER RETENTION POLICY "what_is_time" WE "NOAA_water_database" 3w SHARD DURATION 30 m DEFAULT DURATION >
the method returns an empty result.
Destroyed a retention policy (retention policy drop)
Syntax
DROP RETENTION POLICY <name_polic_retention> ON <name_database>
Parameters
- name_politic_retention : the name of the policy to change
- name_database : database on which it applies
Discover the InfluxDB Shell
Now we know some methods , we will provide to run some tests. Just like MongoDB, InfluxDB for its own command shell that allows to perform all operations on databases. To start it, nothing complicated, just enter Influx in the Terminal.
$ influx Visit https://enterprise.influxdata.com to register for updates, InfluxDB server management, and monitoring. Connected to http://localhost:8086 version v1.1.0 InfluxDB shell version: v1.1.0 >
The exit command allows to get out of the shell.
Note. All the operations described in this paragraph can also be accomplished using commands curl .
Let’s start by creating a database
> CREATE DATABASE basetest > SHOW DATABASES name: databases name ---- _internal basetest
Add a user projetsdiy for this database
> CREATE USER projetsdiy WITH PASSWORD 'password!'
And now we give him all rights based basetest .
> GRANT ALL ON basetest TO projetsdiy >
Now we add a 30-day retention policy
> CREATE RETENTION POLICY "thirty_days" ON basetest DURATION 30d REPLICATION 1 DEFAULT >
Check retention policy
> SHOW RETENTION POLICIES ON basetest name duration shardGroupDuration replicaN default ---- -------- ------------------ -------- ------- autogen 0s 168h0m0s 1 false thirty_days 720h0m0s 24h0m0s 1 true >
It is finished for this first presentation on InfluxDB. There is still much to discover, but it’s more than enough to take charge and start working with. In the next tutorial, we’ll see how to save steps of a DHT22 probe built around MySensors by using Node-RED firmware.
Update
[June 11, 2018] How to install InfluxDB on Raspbian Stretch for Raspberry Pi.
- MQTT router with Node-RED, connect all your Sonoff Tasmota modules to cloudMQTT
- CloudMQTT test, free online MQTT broker. Control Domoticz with the JSON API
- Xiaomi Mijia Honeywell Smoke Detector Test with Domoticz, Emergency Notification with PushOver
- #Test Zigbee2MQTT gateway. Part 2, include Xiaomi Aqara or Mijia accessories to Domoticz with Node-RED [update]
- #Test Zigbee2MQTT project, hack of the Xiaomo Aqara Smart Home Gateway. Part 1: assembly, demo with Node-RED, 3D printed case [update]
- Install Grafana on macOS and Raspbian for Raspberry Pi. Example dashboard for connected object MySensors with Node-RED and InfluxDB [Update]