Knowledgebase

Introduction

InfluxDB is an open-source time-series database server that you can use to build Internet of Things (IoT) applications for data monitoring purposes. Built for developers, InfluxDB's powerful ecosystem handles the massive volumes of time-stamped data produced by sensors and applications. In addition, InfluxDB provides you with the familiarity and ease of a powerful Application Programming Interface (API) for building apps with less code, less effort, and fewer configurations. With its many client/server libraries, InfluxDB supports most modern programming languages, including React, Go, and Python.

The database server ships with enterprise-grade security that makes it suitable to run in a cloud-computing infrastructure. InfluxDB can ingest and handle metrics from events and logs coming from millions of data points per second. A vibrant community also supports it. You don't have to start from scratch as a developer since you can access high-quality end-user documentation for easy integration.

InfluxDB is part of the solutions offered by popular companies like IBM, PayPal, BBOXX, and more. To put things in a better perspective, BBOXX uses InfluxDB to continuously monitor, bill customers, and track power usage alerts from over 85,000 units of solar rooftops dispersed to their users in developing countries. Each customer unit contains an electronic device that connects to a remote InfluxDB to allow BBOXX to control it remotely and provide insight into power usage patterns.

In this guide, you'll install and configure the InfluxDB on Ubuntu 20.04 and unlock the potential of creating a data-driven application that accelerates innovation and decision-making in your projects.

Prerequisites

Before you begin, make sure you have the following:

• An Ubuntu 20.04 server.
• A sudo user.

1. Download and Install the InfluxDB Package

In this step, you'll install the InfluxDB server by pulling the installation files from the official repo maintained at influxdata.com. SSH to your server and use the Linux curl command to download and add the InfluxDB GPG key into your server.

$ sudo curl -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add -

The above command should respond with an OK message.

OK

Add a new influxdb.list repository file to the list of available packages by executing the following command.

$ sudo echo "deb https://repos.influxdata.com/ubuntu bionic stable" | sudo tee /etc/apt/sources.list.d/influxdb.list

Then, update the package information index.

$ sudo apt update

Next, install the influxdb package.

$ sudo apt install influxdb

Once installed, start the influxdb service.

$ sudo systemctl start influxdb

Next, check the status of the InfluxDB server by running the command below.

$ sudo systemctl status influxdb

The InfluxDB package should now be active and loaded on your server.

influxdb.service - InfluxDB is an open-source, distributed, time series da>
    Loaded: loaded (/lib/systemd/system/influxdb.service; enabled; vendor p>
    Active: active (running) since Fri 2021-09-03 06:08:59 UTC; 2min 3s ago
      Docs: https://docs.influxdata.com/influxdb/

Once you've installed the InfluxDB server, you'll make some configuration changes in the next step to secure it.

2. Configure the InfluxDB Server

In this step, you'll configure a new admin user with root privileges for your InfluxDB server. It would be best if you did this before enabling authentication on the configuration file. To do this, execute the influx command. It should start the influx shell and connect to the local InfluxDB instance automatically.

$ influx

Next, you'll receive the following response showing your current connection, port, and version number. The prompt > shows that your InfluxDB server is ready to accept commands.

Connected to http://localhost:8086 version 1.8.9
InfluxDB shell version: 1.8.9
>

To create an admin account, execute the following command and replace EXAMPLE_PASSWORD with a strong value. The admin username is also flexible and you can replace it with an appropriate name (For instance, root or super_user).

> CREATE USER admin WITH PASSWORD 'EXAMPLE_PASSWORD' WITH ALL PRIVILEGES

Next, exit from the InfluxDB shell by executing the quit command.

> quit

The next step is enabling authentication by modifying the main InfluxDB configuration file. Use nano to open the /etc/influxdb/influxdb.conf file.

$ sudo nano /etc/influxdb/influxdb.conf 

Locate the line # auth-enabled = false under the [http] section.

...
[http]
  ...
  # Determines whether user authentication is enabled over HTTP/HTTPS.
  # auth-enabled = false
...

Change the value of auth-enabled from false to true and remove the leading # symbol from the line to uncomment the setting as shown below.

...
[http]
  ...
  # Determines whether user authentication is enabled over HTTP/HTTPS.
  auth-enabled = true
...

Save and close the file. Next, restart the influxdb service to load the new security setting.

$ sudo systemctl restart influxdb

You can now Log in to the InfluxDB server with the admin username and password that you created above by executing the following command.

$ influx -username 'admin' -password 'EXAMPLE_PASSWORD'

You're now authenticated to the influx shell command and once you get the > prompt you can start executing SQL statements. To make sure everything is working, run the SHOW DATABASES command.

> SHOW DATABASES

You should see a default _internal database in the list as shown below. InfluxDB uses this database to store internal runtime metrics for monitoring services.

name: databases
name
----
_internal

Once you've configured and enabled authentication for the InfluxDB server, you'll now set up a sample database in the next step.

3. Creating an InfluxDB Database

Just like other databases, InfluxDB supports most SQL statements in the form of Influx Query Language (InfluxQL). In this step, you'll set up a sample database that stores metrics from a sample water level monitoring system.

Create the water_db database by executing the following command on the influx shell.

> CREATE DATABASE water_db

Once you hit Enter you should get a new prompt > and nothing else will appear. This means you've executed the CREATE DATABASE command without any errors. However, to ensure you've successfully set up the water_db database, run the SHOW DATABASES command.

> SHOW DATABASES

You should see a list of two databases as shown in the following output.

name: databases
name
----
_internal
water_db

Your database is now ready to accept new data. In the next step, you'll create and explore some time-series data in the sample water_db database.

4. Write and Explore InfluxDB Data

From this point forward, you'll execute additional InfluxQL statements against that your new water_db database. Therefore, before you execute any more statements, run the USE command to switch to the new water_db database.

> USE water_db

You should receive the response below showing that you've set the water_db as the active database for new requests.

Using database water_db

You now have a database that can accept writes and queries. Unlike in other SQL databases, data in InfluxDB is organized in a time series format that requires at least 4 main attributes as detailed below:

• time: This is a unique time_stamp recorded automatically when your insert a point into the InfluxDB database.
• measurement: The name of the metric that you're measuring. For instance, cpu_load, water_level, heart_rate, or battery_capacity.
• tags: These are key-value tags containing unique meta data about a measurement. For instance, tank_location=MIAMI OR user=POASAX.
• fields: This is a key-value store that holds the actual data values of what you're measuring. For instance value_in_ft=7.8, or heart_rate_bpm=72.

In simple terms, time is the primary index on the InfluxDB, while measurement is like a table containing columns in the form of fields and tags. Also, a single data record in the InfluxDB is referred to as a point. To insert records in the InfluxDB, you should use the following line protocol syntax.

> INSERT EXAMPLE_MEASUREMENT, TAG_1=VALUE_1, TAG_2=VALUE_2, TAG_N=VALUEN FIELD_1=VALUE_1, FIELD_2=VALUE_2, FIELD_N=VALUE_N

For instance, execute the following commands to insert some fictional points to a water_level measurement to illuminate the InfluxDB query functionalities.

> INSERT water_level,tank_location=MIAMI value_in_ft=10.00
> INSERT water_level,tank_location=SEATTLE value_in_ft=5.4
> INSERT water_level,tank_location=ATLANTA value_in_ft=0.5
> INSERT water_level,tank_location=DALLAS value_in_ft=3.2
> INSERT water_level,tank_location=LOS-ANGELES value_in_ft=1.3

In a production environment, the data above should be generated by on-site water level sensors and relayed to the InfluxDB server via an API. For now, you've entered the values manually to see how the InfluxDB schema works.

To confirm whether you've successfully inserted the points in your water_db server, run a SELECT statement against the water_level measurement. For this statement, you can define the tags (e.g. tank_location) and fields (e.g. value_in_ft) that you want to display.

> SELECT "tank_location", "value_in_ft" FROM "water_level"

You should now receive the following output displaying all the points. Please note how each point was time-stamped as you recorded it in the database.

name: water_level
time                tank_location value_in_ft
----                ------------- -----------
1630660024738274574 MIAMI         10
1630660033290269685 SEATTLE       5.4
1630660040820309594 ATLANTA       0.5
1630660049030041003 DALLAS        3.2
1630660096340252215 LOS-ANGELES   1.3

In addition to selecting all the points, you can filter the records by tags. For instance, run the command below to retrieve measurement data for the tank located in MIAMI.

> SELECT "tank_location", "value_in_ft" FROM "water_level" WHERE tank_location='MIAMI'

You should now see a single MIAMI record as shown below.

name: water_level
time                tank_location value_in_ft
----                ------------- -----------
1630660024738274574 MIAMI         10

To delete any point in the measurement, use the DELETE statement. For instance, to delete the ATLANTA entry, run the command below.

> DELETE FROM water_level WHERE tank_location='ATLANTA'

Run a SELECT statement against the measurement again to check if the deletion succeeded.

> SELECT "tank_location", "value_in_ft" FROM "water_level"

You have now successfully removed the ATLANTA record, as you can confirm from the following output.

name: water_level
time                tank_location value_in_ft
----                ------------- -----------
1630660024738274574 MIAMI         10
1630660033290269685 SEATTLE       5.4
1630660049030041003 DALLAS        3.2
1630660096340252215 LOS-ANGELES   1.3

Apart from the SELECT statements, InfluxDB supports aggregate functions for turning data into powerful insights. For instance, in your sample water level application, you can query the latest level of the tank from DALLAS using the syntax below, provided you've several entries flowing into your database (For instance, after every 5 minutes).

> SELECT LAST("value_in_ft") FROM "water_level" WHERE "tank_location"='DALLAS'

The above command should return the most recent value. Please note, this is where the practical use of the InfluxDB comes into action. You can use the LAST value to make a decision. For instance, if the water tank is empty, you can remotely switch on a pump to feed more water into the tank.

name: water_level
time                last
----                ----
1630660049030041003 3.2

Exit from the InfluxDB server.

> quit

You're able to create and explore the InfluxDB Data. In the next step, you'll query the same data from the inbuilt InfluxDB API.

5. Work with InfluxDB HTTP API

Since InfluxDB was built for developers, it has a very useful API that allows you to query metrics with common tools without writing additional codes. To query data from the water_db database, use the Linux curl command. Replace EXAMPLE_PASSWORD with the correct password value.

$ curl -G 'http://localhost:8086/query?pretty=true' -u admin:EXAMPLE_PASSWORD --data-urlencode "db=water_db" --data-urlencode "q=SELECT \"tank_location\", \"value_in_ft\" FROM \"water_level\""

You should now see the following output with all data points nicely placed in JSON format.

{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "water_level",
                    "columns": [
                        "time",
                        "tank_location",
                        "value_in_ft"
                    ],
                    "values": [
                        [
                            "2021-09-03T09:07:04.738274574Z",
                            "MIAMI",
                            10
                        ],
                        [
                            "2021-09-03T09:07:13.290269685Z",
                            "SEATTLE",
                            5.4
                        ],
                        [
                            "2021-09-03T09:07:29.030041003Z",
                            "DALLAS",
                            3.2
                        ],
                        [
                            "2021-09-03T09:08:16.340252215Z",
                            "LOS-ANGELES",
                            1.3
                        ]
                    ]
                }
            ]
        }
    ]
}

Your InfluxDB server and API are now working as expected.

Conclusion

In this tutorial, you've installed and configured InfluxDB on your Ubuntu 20.04 server. You've then created a sample database and used some useful InfluxQL statements to write and query data into your database. You've also worked with the InfluxDB API using the curl command and returned JSON formatted data from your application without writing any complex code. Follow the examples in this guide to create flexible and highly responsive time-series applications in your next project.