SiriDB - Connector

The SiriDB Connector is a self-contained Python driver for communicating with SiriDB servers. This manual describes how to install and configure SiriDB Connector for Python 3, and how to use it to develop database applications.

• Installation
• Quick usage
• SiriDBClient
  • connect
  • insert
  • query
  • close
• Exception codes
• Version info

Installation

From PyPI (recommended)

pip install siridb-connector

From source code

python setup.py install

Quick usage

import asyncio
import time
import random
from siridb.connector import SiriDBClient

async def example(siri):
    # Start connecting to SiriDB.
    # .connect() returns a list of all connections referring to the supplied
    # hostlist. The list can contain exceptions in case a connection could not
    # be made.
    await siri.connect()

    try:
        # insert
        ts = int(time.time())
        value = random.random()
        await siri.insert({'some_measurement': [[ts, value]]})

        # query
        resp = await siri.query('select * from "some_measurement"')
        print(resp)

    finally:
        # Close all SiriDB connections.
        siri.close()


siri = SiriDBClient(
    username='iris',
    password='siri',
    dbname='dbtest',
    hostlist=[('localhost', 9000)],  # Multiple connections are supported
    keepalive=True)

loop = asyncio.get_event_loop()
loop.run_until_complete(example(siri))

SiriDBClient

Create a new SiriDB Client. This creates a new client but .connect() must be used to connect.

siri = SiriDBClient(
    username=<username>,
    password=<password>,
    dbname=<dbname>,
    hostlist=[(<host>, <port>, {weight: 1}, {backup: False})],
    loop=None,
    keepalive=True,
    timeout=10,
    inactive_time=30,
    max_wait_retry=90)

Arguments:

• username: User with permissions to use the database.

• password: Password for the given username.

• dbname: Name of the database.

• hostlist: List with SiriDB servers (all servers or a subset of servers can be in this list).

  Example:

  hostlist=[ ('server1.local', 9000, {'weight': 3}),
             ('server2.local', 9001),
             ('backup1.local', 9002, {'backup': True}) ]
  

  Each server should at least have a hostname and port number. Optionally you can provide a dictionary with extra options.

  Available Options:

  • weight : Should be a value between 1 and 9. A higher value gives the server more weight so it will be more likely chosen. (default 1)
  • backup : Should be either True or False. When True the server will be marked as backup server and will only be chosen if no other server is available. (default: False)

Keyword arguments:

• loop: Asyncio loop. When 'None' the default event loop will be used.
• keepalive: When 'True' keep-alive packages are send every 45 seconds.
• timeout: Maximum time to complete a process, otherwise it will be cancelled.
• inactive_time: When a server is temporary unavailable, for example the server could be paused, we mark the server as inactive after x seconds.
• max_wait_retry: When the reconnect loop starts, we try to reconnect in 1 second, then 2 seconds, 4, 8 and so on until max_wait_retry is reached and then use this value to retry again.

SiriDBClient.connect

Start connecting to SiriDB. .connect() returns a list of all connections referring to the supplied hostlist. The list can contain exceptions in case a connection could not be made.

Optionally the keyword argument timeout can be set. This will constrain the search time for a connection. Exceeding the timeout will raise an .TimeoutError.

siri.connect(timeout=None)

SiriDBClient.insert

Insert time series data into SiriDB. Requires a 'dictionary' with at least one series. Optionally the timeout can be adjusted (default: 300).

siri.insert(data, timeout=300)

SiriDBClient.query

Query data out of the database. Requires a string containing the query. More about the query language can be found here. The documentation about the query language will inform you about a number of useful aggregation and filter functions, different ways of visualizing and grouping the requested data, and how to make changes to the set up of the database. Optionally a time_precision (SECOND, MICROSECOND, MILLISECOND, NANOSECOND) can be set. The default None sets the precision to seconds. Futhermore the timeout can be adjusted (default: 60).

from siridb.connector import (SECOND,
                              MICROSECOND,
                              MILLISECOND,
                              NANOSECOND)

siri.query(query, time_precision=None, timeout=60)

SiriDBClient.close

Close the connection.

siri.close()

Check if the connection is closed.

siri.is_closed

Exception codes

The following exceptions can be returned:

• AuthenticationError: Raised when credentials are invalid or insufficient.
• IndexError: Raised when the database does not exist (anymore).
• InsertError (can only be raised when using the .insert() method): Make sure the data is correct because this only happens when SiriDB could not process the request.
• OverflowError (can only be raised when using the .insert() method): Raised when integer values cannot not be packed due to an overflow error (integer values should be signed and not more than 63 bits).
• PoolError: SiriDB has no online server for at least one required pool. Try again later after some reasonable delay.
• QueryError (can only be raised when using the .query() method): Make sure the query is correct because this only happens when SiriDB could not process the query. Consult the documentation about the query language can be found.
• RuntimeError: Raised when a general error message is received. This should no happen unless a new bug is discovered.
• ServerError: Raised when a server could not perform the request, you could try another server if one is available. Consult the documentation how to get additional status information about the servers.
• TimeoutError: Raised when a process lasts longer than the timeout period
• TypeError: Raised when an unknown package is received (might be caused by running a different SiriDB version).
• UserAuthError: The user as no rights to perform the insert or query. Consult the documentation how to change the access rights.