utsdb

uTSDB
=====

link:https://gitlab.com/miska/utsdb/-/pipelines/master/latest[image:https://gitlab.com/miska/utsdb/badges/master/pipeline.svg[Pipeline status]]
link:https://goreportcard.com/report/gitlab.com/miska/utsdb[image:https://goreportcard.com/badge/gitlab.com/miska/utsdb[Go Report Card]]
link:https://gitlab.com/miska/utsdb/-/tags/[image:https://gitlab.com/miska/utsdb/-/badges/release.svg[Release binaries]]
image:https://gitlab.com/miska/utsdb/badges/master/coverage.svg[Coverage]
link:https://openhub.net/p/utsdb[image:https://openhub.net/p/utsdb/widgets/project_thin_badge?format=gif&ref=Thin+badge[OpenHub]]

This is minimal implementation of time series database written in go. Goal is
to have something simple, easy to deploy with HTTP API to store time series
data in traditional SQL databases.

Setup
-----

Running uTSDB is simple. You just need to run `utsdb` binary with proper
environment.

Environment
~~~~~~~~~~~

Currently there are no command line options and the behaviour is controlled via
environment flags.

`LISTEN`
^^^^^^^^

Variable `LISTEN` specifies IP and port to listen on. Default in `:8080`.

`DB_ENGINE`
^^^^^^^^^^^

This variable specifies the database engine to use. Currently only `sqlite3` is
supported, but in the future there will be option to use MySQL/MariaDB as well.
For now, only reasonable value is `sqlite3`.

`DB`
^^^^

Specifies database to connect to. In SQLite case, it is path to the file that
we want to store data into. Default value is `./utsdb.sqlite`.

Security
~~~~~~~~

Different credentials and access rights are not supported at the moment. But
everything can be solved easily by using reverse proxy and applying rules
there. One advantage is that `bucket` is always part of URL, so you can manage
access rights to different buckets differently. Based on the method used, you
can also distinguish who can write, read or manage data.

nginx example config
^^^^^^^^^^^^^^^^^^^^

-------------------------------------------------------------------------------
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name utsdb.example.com;

  auth_basic off;

  include ssl_conf;

  location /test {
    auth_basic "Your uTSDB credentials";
    if ($request_method == "GET") {
      auth_basic_user_file "/etc/nginx/utsdb_pass_ro";
    }
    if ($request_method == "POST") {
      auth_basic_user_file "/etc/nginx/utsdb_pass";
    }
    proxy_set_header Authorization "";
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass_request_headers on;
    proxy_pass http://127.0.0.1:8080;
  }
-------------------------------------------------------------------------------

API
---

`POST /bucket`
~~~~~~~~~~~~~~

To store some data issue a `POST` request to URL in the form _/bucket_. You can
use different buckets to store data separately.

Post data format
^^^^^^^^^^^^^^^^

Body of the request can consist of one or more lines with space separated
columns. Every line has to have two,three or four columns.

There are two different formats two columns and three columns ones. But both of
them can have added optional timestamp in unix time prepended with `@`.

3 colums
++++++++

If the line has three columns, first column is the name of the measurement,
second is comma separated list of key/value pairs to serve as tags and the last
column is the value which can be either integer or a floating point number.

2 columns
+++++++++

If line contains only two columns, both of them contain comma separated list of
key value pairs. In first column are stored tags. In second column, pairs
represent measurement name and it's value.

Example
+++++++

Bellow you can see a valid data mixing both three and two columns format.

-------------------------------------------------------------------------------
temperature location=inside,room=bedroom 22.5 @1669191587
temperature location=inside,room=livingroom 24.5
temperature location=outside -4.8
pressure  1025
location=inside,room=bathroom temperature=28,humidity=90
-------------------------------------------------------------------------------

`GET /`_bucket_
~~~~~~~~~~~~~~~

Return all data from the specified bucket as a JSON.

`GET /`_bucket_`/`_measurement_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

More specific query for the data. Return all measurements of specified type
from the specified bucket as a JSON.