This chapter explains how to quickly install, run, and use HSQLDB version 1.7.2 on UNIX.

HSQLDB has lots of great optional features. I intend to cover very few of them. I do intend to cover what I think is the most common UNIX setup: To run a multi-user database with permament data persistence. (By the latter I mean that data is stored to disk so that the data will persist across database shutdowns and startups). I also cover how to run Hsqldb as a system daemon.

Go to http://sourceforge.net/projects/hsqldb and click on the "files" link. Look for "hsqldb_1_7_2" under lower-case "hsqldb". Click on "show only this release" link right after "hsqldb_1_7_2".

Click the "hsqldb_1_7_2" link to find out what version of Java this binary HSQLDB distribution was built with. Don't hold me to it, but if you get your distro from us at SourceForge, it will probably be built with Java 1.4. Choose a binary package format that will work with your UNIX variant and which supports your Java version. Otherwise choose the hsqldb_1_7_2.zip file. Click the filename to download it. (If you have an older version of Java and there's nothing preventing you from upgrading it, you'll probably be happier in the end if you upgrade Java rather than downgrading HSQLDB).

If you want an rpm, then click "hsqldb" in the "free section" of http://www.jpackage.org/. Hopefully, the JPackage folk will document what JVM versions their rpm will support (currently they document this neither on their site nor within the package itself). Download the package you want, making sure that you get version 1.7.2 of HSQLDB. (I really can't document how to download from a site that is totally beyond my control).

Binary installation depends on the package format that you downloaded.

Take a look at the files you installed. (Under hsqldb for zip file installations. Otherwise, use the utilities for your packaging system). The most important file of the hsqldb system is hsqldb.jar, which resides in the directory lib.

If the description of your distribution says that the hsqldb.jar file will work for your Java version, then you are finished with installation. Otherwise you need to build a new hsqldb.jar file.

If you followed the instructions above and you still don't know what Java version your hsqldb.jar supports, then read HSQLDB_HOME/readme.txt and HSQLDB_HOME/index.html. If that still doesn't help, then you can just try your hsqldb.jar and see if it works, or build your own.

To use the supplied hsqldb.jar, just skip to the next section of this document. Otherwise build a new hsqldb.jar.

See the Building Hsqldb version 1.7.2 appendix if you want to build anything other than hsqldb.jar with all default settings.

If you installed from an OS-specific package, you may already have a database instance and server pre-configured. See if your package includes a file named server.properties (make use of your packaging utilities). If you do, then I suggest that you still read this section while you poke around, in order to understand your setup.

Copy the file HSQLDB_HOME/src/org/hsqldb/sample/sqltool.rc to the HSQLDB_OWNER's home directory. Use chmod to make the file readable and writable only to HSQLDB_OWNER.

# $Id: sqltool.rc,v 1.11 2004/07/18 21:34:35 unsaved Exp $

# This is a sample SqlTool configuration file, a.k.a. rc file.

# You can run SqlTool right now by copying this file to your home directory
# and running
#    java -jar /path/to/hsqldb.jar mem
# This will access the first urlid definition below in order to use a 
# personal Memory-Only database.

# If you have the least concerns about security, then secure access to
# your sqltool.rc file.
# See the documentation for SqlTool for various ways to use this file.

# A personal Memory-Only database.
urlid mem
url jdbc:hsqldb:mem:memdbid
username sa
password

# This is for a hsqldb Server running with default settings on your local
# computer (and for which you have not changed the password for "sa").
urlid localhost-sa
url jdbc:hsqldb:hsql://localhost
username sa
password


###########################################################################
# Template for a urlid for an Oracle database.
# You will need to put the oracle.jdbc.OracleDriver class into your 
# classpath.
# In the great majority of cases, you want to use the file classes12.zip
# (which you can get from the directory $ORACLE_HOME/jdbc/lib of any
# Oracle installation compatible with your server).
# Since you need to add to the classpath, you can't invoke SqlTool with
# the jar switch, like "java -jar .../hsqldb.jar..." or 
# "java -jar .../hsqlsqltool.jar...".
# Put both the HSQLDB jar and classes12.zip in your classpath (and export!)
# and run something like "java org.hsqldb.util.SqlTool...".

#urlid cardiff2
#url jdbc:oracle:thin:@aegir.admc.com:1522:TRAFFIC_SID
#username blaine
#password secretpassword
#driver oracle.jdbc.OracleDriver
###########################################################################


###########################################################################
# Template for a urlid for a Postgresql database.
# You will need to put the org.postgresql.Driver class into your 
# classpath.
# The postgresql jar will be named postgresql.jar (if you built Postgresql 
# from source), or something like pg73b1jdbc3.jar or jdbc7.2x-1.2.jar.
# You can obtain it from a client or server Postgresql installation, or 
# download it from http://jdbc.postgresql.org/download.html.
# Notice that the jar file names (other than "postgresql.jar") contain both
# the target Postgresql server version and the client-side JDBC level (which
# is determined by your client-side Java version, as explained at
# http://jdbc.postgresql.org/download.html).
# I recommend the latest production version for your JDBC version.  The 
# later JDBC drivers work better even with older Postgresql servers.
# (E.g. \dt won't list owners with an older driver).
# N.b.: Suse Linux 9.1 users should download a new driver from the PG site,
# since Suse distributes the 7.3 drivers with Postgresql 7.4 (why???).
# Since you need to add to the classpath, you can't invoke SqlTool with
# the jar switch, like "java -jar .../hsqldb.jar..." or 
# "java -jar .../hsqlsqltool.jar...".
# Put both the HSQLDB jar and the Postgresql jar in your classpath (and
# export!) and run something like "java org.hsqldb.util.SqlTool...".
# N.b.:  I notice that Postgresql is unusual in that it does not do an
# implicit commit before DDL commands.  If you get an error message 
# "... cannot run inside a transaction block", just run "commit;" and retry.

#urlid commerce
#url jdbc:postgresql://dbsvr2/commercedb
#username blaine
#password obscured
#driver org.postgresql.Driver
###########################################################################


###########################################################################
# Template for a TLS-encrypted HSQLDB Server.
# Remember that the hostname in hsqls (and https) JDBC URLs must match the
# CN of the server certificate (the port and instance alias that follows 
# are not part of the certificate at all).
# You only need to set "truststore" if the server cert is not approved by
# your system default truststore (which a commercial certificate probably
# would be).

#urlid tls
#url jdbc:hsqldb:hsqls://db.admc.com:9001/lm2
#username blaine
#password asecret
#truststore /home/blaine/ca/db/db-trust.store
###########################################################################

We will be using the "localhost-sa" sample urlid definition from the config file. The JDBC URL for this urlid is jdbc:hsqldb:hsql://localhost. That is the URL for the default database instance of a HSQLDB Server running on the default port of the local host. You can read about URLs to connect to other instances and other servers in the Advanced Topics chapter.

Run SqlTool.

    java -jar path/to/hsqldb.jar localhost-sa

    set password "newpassword";

When you're finished playing, exit with the command \q.

If you changed the SA password, then you need to fix the password in the sqltool.rc file accordingly.

You can, of course, also access the database with any JDBC client program. See the First JDBC Client Example appendix. You will need to modify your classpath to include hsqldb.jar as well as your client class(es). You can also use the other HSQLDB client programs, such as org.hsqldb.util.DatabasManagerSwing, a graphical client with a similar purpose to SqlTool.

You can use any normal UNIX account to run the JDBC clients, including SqlTool, as long as the account has read access to the hsqldb.jar file and to an sqltool.rc file. See the SqlTool chapter about where to put sqltool.rc, how to execute sql files, and other SqlTool features.

Connect to the database as SA (or any other Administrative user) and run CREATE USER to create new accounts for your database instance. HSQLDB accounts are database-instance-specific, not Server-specific.

There are two classes of database accounts, Admin accounts and non-Admin accounts. Admins have privileges to do anything, non-Admins may be granted some privileges, but may never create or own database objects. When you first create a hsqldb database, it has only one database user-- SA, an Admin account, with no password set. You should set a password (as described above). You can create as many additional Admin users as you wish. Each Admin user has a unique user name (and optional password), but these accounts are otherwise indistinguishable. These accounts are created by appending the keyword "ADMIN" to the CREATE USER command.

If you create a user without the ADMIN tag, it will be a Non-Admin account. These users can not create or own objects, and, by default, they can't use any database objects. The user will then be able to perform operations which have been granted to the pseudo-user PUBLIC. To give the user additional privileges (even the privilege to read data), an Admin user must grant those rights to the user (or to PUBLIC).

Since only people with a database account may do anything at all with the database, it is often useful to permit other database users to view the data in your tables. To optimize performance, reduce contention, and minimize administration, it is often best to grant SELECT to PUBLIC on any object that needs to be accessed by multiple database users (with the significant exception of any data which you want to keep secret).

Do a clean database shutdown when you are finished with the database instance. You need to connect up as SA or some other Admin user, of course. With SqlTool, you can run

    java -jar path/to/hsqldb.jar --noinput --sql 'shutdown;' localhost-sa

You can, of course, run HSQLDB through inittab on System V UNIXes, but usually an init script is more convenient and manageable. This section explains how to set up and use our UNIX init script. Our init script is only for use by root. (That is not to say that the Server will run as root-- it usually should not).

The main purpose of the init script is to start up a Server with the database instances specified in your server.properties file; and to shut down all of those instances plus additional urlids which you may (optionally) list in your init script config file. These urlids must all have entries in a sqltool.rc file. If, due to firewall issues, you want to run a WebServer instead of a Server, then make sure you have a healthy WebServer with a webserver.properties set up, adjust your URLs in sqltool.rc, and set TARGET_CLASS in the config file.

After you have the init script set up, root can use it anytime to start or stop HSQLDB. (I.e., not just at system bootup or shutdown).

    sh -x path/to/hsqldb start

    sh -x path/to/hsqldb start > /tmp/hstart.log 2>&1