Chapter 2. How to Install and Run the sample HSQLDB Server and Perl Script

Download the binary distribution with name like hsqldb-ber-0.1a.zip to the computer to house your database server. Unzip the zip file to any directory. Everything will expand into a new directory named something like hsqldb-ber-0.1a. We hereafter call this the HSQLDB-BER installation directory.

You need to have Perl and some specific Perl modules installed on the servers that will execute your perl scripts. If this is your first install, then I suggest that you hold off on that and install Perl and the Perl modules on the database server computer. This makes it extremely easy to run the sample configuration and give yourself a warm fuzzy.

On the computers to host your Perl scripts, install the Perl modules DBI, Convert::BER, and DBD::JDBC if any of them are not already installed.

Tip

Before you run make for DBD::JDBC, edit the file JDBC.pm and comment out the two lines containing SQL_BIGINT. These lines are obsolete and will cause things to fail.

I recommend that you don't bother running the supplied tests. The results aren't worth the entire pain-in-the-ass to get the test itself to run. When I have time, I'll try to track down the author of DBD::JDBC and get the SQL_BIGINT problem taken care of at the source.

The documentation of DBD::JDBC will say that the module is for use with a Java proxy server. Disregard that-- It is true when using the DBD::JDBC-supplied proxy-server, but you will be using a direct HSQLDB database server (which the main point of the HSQLDB-BER product).

There will be a subdirectory of your HSQLDB-BER installation directory named samples. Cd into that directory and run

Example 2.1. Running a HSQLDB Server + BerServer

    java -jar ../hsqldb-ber.jar org.hsqldb.Server org.hsqldb.BerServer

This will start a "hsql" protocol JDBC Server, and a BER protocol Server which are serving two memory-only database instances. If you want to run only a BER Server, then just run

java -cp path/to/hsqldb-ber.jar:path/to/hsqldb.jar:path/to/dbd_jdbc.jar \
    org.hsqldb.BerServer

(Windows users user ";" in place of ":"). Let the Server continue to run. Put it in the background or get another shell so you can run the sample perl script against this Server. (It is incredibly easy to change the database instances to be persistent. The only reason I don't have it persisting by default is so that this distribution can be run from read-only media like CDs. Just change the occurrences of mem: in the server.properties and berserver.properties to file:.)

Once again, cd to the samples directory under your hsqld-ber installation diretory. Execute the perl script sample.pl. (You can make this script "executable". It is only delivered non-executable due to a portability constraint of the build tool which we use).

You can manage your database on the command-line by running

Example 2.2. Managing HSQLDB with SqlTool

    java -jar ../hsqldb.jar --rcfile sqltool.rc playdb-hsql

from the same directory; or

Example 2.3. Managing HSQLDB with DatabaseManager

java -cp ../hsqldb.jar --rcfile sqltool.rc org.hsqldb.util.DatabaseManagerSwing playdb-hsql

for a GUI.