Set up HSQLDB on macOS: Java, JDBC, server mode and tools

A reproducible guide to running HyperSQL 2.7.4 on a Mac, from installing Java to JDBC URLs, server mode, the GUI manager and clean shutdowns.

Updated on October 28, 2026

HyperSQL (HSQLDB) is a relational database written entirely in Java. This guide walks through a clean setup on macOS, on both Apple Silicon and Intel, with the current 2.7.4 release.

In 30 seconds Install a JDK, add the org.hsqldb:hsqldb 2.7.4 dependency, connect with a jdbc:hsqldb:file: URL as user SA with an empty password, and close the database cleanly. Use server mode only when several processes need the same data.

What you need

A JDK. HyperSQL 2.7.4 is compatible with Java 11 or later, and the download also includes a JDK 8 build of the jar.
A Mac running Apple Silicon or Intel. Homebrew's temurin@21 cask lists installers for both, and Adoptium offers macOS PKG installers.
Maven or Gradle, or simply the jar from the Maven Central listing.

Add the HSQLDB dependency to your build (Maven or Gradle, shown below).
Open a database with a file, mem or res JDBC URL.
Start the Swing manager or SqlTool to inspect your tables.
Close the database cleanly so the lock and log files are removed.

Install Java and add the dependency

On macOS the Eclipse Temurin 21 JDK installs through Homebrew with the cask below.

brew install --cask temurin@21
java -version

The coordinates are org.hsqldb:hsqldb, and version 2.7.4 is published on Maven Central. A jdk8 classifier jar also exists, hsqldb-2.7.4-jdk8.jar, for older runtimes. SqlTool is published separately as org.hsqldb:sqltool.

<dependency>
  <groupId>org.hsqldb</groupId>
  <artifactId>hsqldb</artifactId>
  <version>2.7.4</version>
</dependency>

implementation 'org.hsqldb:hsqldb:2.7.4'

Choose how the database runs

The Running and Using HyperSQL chapter lists the URL forms. The driver class is org.hsqldb.jdbc.JDBCDriver, the user is SA and the password is empty.

jdbc:hsqldb:file:testdb: a database stored in files, accessed in-process.
jdbc:hsqldb:mem:mymemdb: in memory only, gone when the process ends.
jdbc:hsqldb:res:org.my.path.resdb: a database read from the classpath.
jdbc:hsqldb:hsql://localhost/xdb: a connection to a running server.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

public class Demo {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:hsqldb:file:testdb;shutdown=true";
        try (Connection c = DriverManager.getConnection(url, "SA", "");
             Statement s = c.createStatement()) {
            s.execute("CREATE TABLE IF NOT EXISTS item (id INT PRIMARY KEY, name VARCHAR(50))");
            s.execute("INSERT INTO item VALUES (1, 'first')");
        }
    }
}

A terminal on a Mac showing a Java program creating and querying an embedded HSQLDB database — An embedded file database needs only the jar and a JDBC URL. Image: Unsplash — silver imac on brown wooden desk

Server mode

When several processes must share one database, run the server. The class is org.hsqldb.server.Server and its options take two dashes. The listeners chapter gives this form, where xdb is the public name clients use.

java -cp ../lib/hsqldb.jar org.hsqldb.server.Server --database.0 file:mydb --dbname.0 xdb

The default port is 9001, and clients connect with jdbc:hsqldb:hsql://localhost/xdb. You can append database properties to the path, for example file:mydb;hsqldb.tx=mvcc. Alternatively, put the options in a server.properties file in the directory where you start the server.

server.database.0=file:mydb
server.dbname.0=xdb
server.port=9001

Inspect data with the bundled tools

The Swing database manager starts straight from the jar. SqlTool is a command line client shipped in sqltool.jar.

java -cp hsqldb.jar org.hsqldb.util.DatabaseManagerSwing

Files, git and clean shutdown

A file database named testdb consists of testdb.properties, .script, .data, .backup and .lobs. While the database is open, testdb.log and testdb.lck also exist; both are removed at a normal SHUTDOWN. Those two are runtime artifacts, so keep them out of version control if you commit the rest of the database.

# .gitignore
testdb.lck
testdb.log

Close the database with the SQL command SHUTDOWN; active transactions are rolled back. Or add shutdown=true to the URL, as in jdbc:hsqldb:file:/opt/db/testdb;shutdown=true, so the database closes when the last connection does.

Tip Commit .properties and .script only after a clean shutdown, so the snapshot you store is complete and consistent.

Common problems

Java not found: run java -version in the same terminal; if it fails, reinstall the JDK and open a new shell.
Wrong Java version: 2.7.4 targets Java 11 or later; on older runtimes use the JDK 8 jar from the download.
Cannot connect to the server: check that the URL uses hsql://localhost/xdb with the alias you set in --dbname.0, and the port you configured (default 9001).
Leftover .lck or .log files: they belong to an open database and are removed at a normal SHUTDOWN, so check that your code or URL closes it.

What changed since 2020

The latest release is 2.7.4, published in October 2024. It adds features from the SQL:2023 standard, including ANY_VALUE and LISTAGG. The download now contains Java 11 module jars alongside Java 8 jars. Recent releases also added JSON constructor functions and Java 8 java.time support in JDBC.

A project folder listing HSQLDB database files beside a gitignore that excludes the lock and log files — Keep runtime files out of the repository. Image: Unsplash — a desktop computer sitting on top of a wooden desk

Original source: HyperSQL

Article generated with AI.larebelion