LucidDbGettingStarted

This page is a step-by-step guide to setting up and running a LucidDB binary distribution on Linux. (NEW: or MacOS!) For Windows, everything is pretty much the same except the archive comes in a zipfile, the scripts are .bat files instead of shell scripts, and you may need to install the Visual C++ 2008 Redistributable Package. (Cygwin users, note this mailing list thread.)

Prerequisites

In a linux environment, there are generally only two pieces of software that need to be installed before running LucidDB.

1. Java 1.6 or later
2. libaio - Linux-native asynchronous I/O access library

Debian/Ubuntu package: libaio1

apt-get install libaio1

CentOS/Redhat package: libaio

yum install libaio

Install

To get started, you must obtain and unpack an archive of the binary distribution. The archive will be named something like luciddb-bin-linux64-0.9.4.tar.bz2, and can be unpacked with:

tar xjf luciddb-bin-linux64-0.9.4.tar.bz2

This will create a directory luciddb-0.9.4, which we will refer to as the LucidDB home directory. The next step is to run a one-time installation script. Before you do this, you must first export environment variable JAVA_HOME to reference the installed location of your Java runtime environment. This environment variable needs to be set permanently, so it's best to put it in your login script. For example, if you are using bash as your shell, add the following line to ~/.bash_profile, using the correct location for your JRE (make sure it's Java 1.6 or higher), and then re-login:

export JAVA_HOME=/usr/java/j2sdk

Now, run the installation script:

cd luciddb-0.9.4/install
./install.sh

If you didn't set JAVA_HOME correctly, you should get a corresponding error message. Otherwise, if all goes well, you'll see a lot of script output, ending with the following line:

echo $LOCALCLASSPATH >$BIN_DIR/classpath.gen

This saved the classpath needed at runtime, so now you should be ready to go.

Start the server

To start the server, run these commands:

cd ../bin
./lucidDbServer

You should see the following message in the same console:

Server personality:  LucidDB
Loading database...
Starting network...
Server now listening for HTTP connections on port 8034; enter !quit to stop

While the server is running, the console in which it started is tied up waiting for the !quit command.

(If you get an error about libaio, follow the instructions in the FAQ to fix the problem.)

Connect from a client

Start another shell and run the command-line JDBC client to test out a SQL connection to the server:

cd luciddb-0.9.4/bin
./sqllineClient

You should see a prompt like this:

Connecting to jdbc:luciddb:http://localhost
Connected to: LucidDB (version 0.9.4)
Driver: LucidDbJdbcDriver (version 0.9)
Autocommit status: true
Transaction isolation: TRANSACTION_REPEATABLE_READ
sqlline version 1.0.8-eb by Marc Prud'hommeaux
0: jdbc:luciddb:http://localhost>

Typing help at this prompt will tell you more about the terminal based java SQL client you have just invoked. !quit exits the client. More documentation for the sqlline product can be found here [Sqlline users guide ]

(If you have problems here on versions <= 0.9.1, it's probably because RMI is very sensitive to /etc/hosts configuration; see the Eigenbase wiki for help. 0.9.2 uses HTTP and should not be affected by the RMI issue above.)

Execute SQL

Enter a query at the prompt:

select schema_name from sys_root.dba_schemas;

You should get a result set like this:

0: jdbc:luciddb:http://localhost> select schema_name from sys_root.dba_schemas;
+---------------------+
|     SCHEMA_NAME     |
+---------------------+
| SYS_BOOT            |
| JDBC_METADATA       |
| MGMT                |
| SQLJ                |
| INFORMATION_SCHEMA  |
| APPLIB              |
| SYS_ROOT            |
+---------------------+

Congratulations! LucidDB is up and running.

Unicode Support (Optional)

NOTE: Unicode support is only available starting with the 0.8.1 32-bit prererelease. Earlier releases only support ISO-8859-1.

If you are going to be loading international character data (in particular, non Western European), execute this command to convert the server installation to Unicode before going any further:

call sys_root.change_default_character_set_to_unicode();

If you are only going to be loading ISO-8859-1 data, you don't need to do this (and storage will be slightly more efficient as single-byte rather than double-byte).

Shut down

Enter !quit in the client window to close the connection, and then !quit in the server console to shut down LucidDB.

Scripting Lucid

At some point you will want to perform backups of your database and execute scripts against LucidDB to fill it with data or take other actions.
In a Linux environment this is extremely easy:

bjackson@sc-vm01-lnx:/opt/luciddb-0.9.4/bin$ echo '!run /path/to/script/myscript.sql' | ./sqllineClient

The above example would cause the command !run /path/to/scripts/myscript.sql to be issued once ./sqllineClient had loaded and cause each line in the sql script to be executed in turn. All commands beginning with an exclamation point (!run, !quit, etc.) come from the software sqlline. sqlline is a terminal based java SQL client packaged by default with LucidDB. sqlline documentation can be found here [sqlline documentation].

Backing up is another useful case for this:

echo '-e "CALL SYS_ROOT.BACKUP_DATABASE( '/backups', 'FULL', 'UNCOMPRESSED' )"' | ./sqllineClient

You can discover more about performing backup and restore as well as other operations by reading documentation here: LucidDbSystemProcedures

While scripting the execution of sqllineClient it is important to remember that the character escaping rules of your shell (BASH) apply. For example if you intend to write the following SQL and execute it against LucidDB through sqllineClient you would take your idea:

0: jdbc:luciddb:http://localhost> select statement from table(sys_root.generate_ddl_for_schema('LOCALDB', 'TESTING'));

Translating to the final command at the BASH shell of:

echo select statement from table\(sys_root.generate_ddl_for_schema\(\'LOCALDB\', \'TESTING\'\)\)\; | ./sqllineClient > report.txt

Notice the \ which escape all the ( ) ' ; marks in the SQL command being pipped over to the ./sqllineClient command. If you fail to escape like this and just single quote your string, BASH will strip out your single quotes or similar thing before the command is passed over to sqllineClient.

What next?

You can find out more about the sqlline client here.

If you get tired of sqlline, you might want to try setting up a GUI client. LucidDbSquirrel tells how.

LucidDbDocs has more documentation for learning about the rest of the system. You might want to start with the LucidDbEtlTutorial, and then try loading up some of your own data and running queries against it. Or set up Mondrian for multi-dimensional analysis as described in LucidDbOlap.

If you encounter problems, check the LucidDbUserFaq, and if you still can't figure it out, try the mailing list (luciddb-users at lists.sf.net; you may be able to find a solution to your problem by reading the archives). There's also an IRC channel ##luciddb at irc.freenode.net.

If you are developing an application in a language other than Java, see LucidDbNonJavaClients.