Getting Started With Blackray

- Installation
- Creating a Database
- Accessing a Database
- Accessing a Database With SQL Relay
- Blackray Quirks

Installation and Configuration

As of version 0.10.0, Blackray provides a database listener that speaks the PostgreSQL protocol. As such, SQL Relay can be used to connect to a Blackray database by configuring it to use a PostgreSQL database connection daemon and aiming it at the Blackray database.

I have only built Blackray from source on a Fedora Linux system. The source code can be downloaded from blackray.org and pre-built packages are available for a variety of plaforms.

Detailed instructions for downloading, extracting and building the source as well as installation, configuration, creation of database instances and accessing the database are available in the Documentation section of the Blackray site. They should be sufficient to get you started.

I would recommend running Blackray as a non-root user. To do so, just create a blackray user and group and make the blackray installation owned by that user. For instance, if you installed it under /opt/blackray, then use the following command to set the ownership:

> chown -R blackray:blackray /opt/blackray

Starting the Database at Boot Time

To start Blackray at boot time, you'll need to install a script like the following to start/stop the database at boot/shutdown time.

>     #!/bin/sh

>     case "$1" in
>             start)
>     		su -l blackray -s /opt/blackray/bin/blackray -c /opt/blackray/etc/blackray.conf start
>     		su -l blackray -s /opt/blackray/bin/blackray -c /opt/blackray/etc/blackray.conf start Default
>                     ;;
>             stop)
>     		su -l blackray -s /opt/blackray/bin/blackray -c /opt/blackray/etc/blackray.conf stop Default
>     		su -l blackray -s /opt/blackray/bin/blackray -c /opt/blackray/etc/blackray.conf stop
>                     ;;
>             *)
>                     echo $"Usage: $0 {start|stop}"
>                     exit 1
>     esac

>     exit 0

Install this script and run it with the "start" option to start up the database. Running it with the "stop" option shuts the database down. To access a database, it must be running.

This script starts an instance called Default. If you want to start/stop a different instance then you should change that. If you want to start/stop multiple instances then you should add additional lines like the ones that start and stop the Default instance, substituting Default for the names of your instances.

Accessing a Database With SQL Relay

Accessing Blackray from SQL Relay requires an instance entry in your sqlrelay.conf file for the instance that you want to access. Here is an example sqlrelay.conf which defines an SQL Relay instance called blackraytest. This instance connects to the intance of Blackray running on the remote server testhost on port 5432.

Note the dbase="postgresql" parameter. SQL Relay is configured to speak the PostgreSQL protocol and aimed at the Blackray database. This works because Blackray supports the PostgreSQL protocol.

    <?xml version="1.0"?>
    <!DOCTYPE instances SYSTEM "sqlrelay.dtd">
    <instances>

            <instance id="blackraytest" port="9000" socket="/tmp/blackraytest.socket" dbase="postgresql" connections="3" maxconnections="5" maxqueuelength="0" growby="1" ttl="60" endofsession="commit" sessiontimeout="600" runasuser="nobody" runasgroup="nobody" cursors="5" authtier="listener" handoff="pass">
                    <users>
                            <user user="blackraytest" password="blackraytest"/>
                    </users>
                    <connections>
                            <connection connectionid="blackraytest" string="host=testhost;port=5432;" metric="1"/>
                    </connections>
            </instance>

    </instances>

Now you can start up this instance with the following command.

> sqlr-start -id blackraytest

To connect to the instance and run queries, use the following command.

> sqlrsh -id blackraytest

The following command shuts down the SQL Relay instance.

> sqlr-stop blackraytest

Blackray Quirks

The Blackray database is an in-memory database and doesn't support insert, update or delete queries, or create table queries. All data must be loaded using an external program from csv files. Data can be loaded at any time, and you can drop tables and alter them, but there is no way to update or delete rows except to update the csv files and reload them. Since it's an in-memory database, no data is stored permanantly unless you explicitly take a snapshot.

These are a lot of quirks, but the trade-off is performance.