備忘録：HSQLDB (HyperSQL Database)の使用方法

HSQLDB (HyperSQL Database)の使い方についての備忘録。
https://hsqldb.org/

動作環境

• macOS 14.4.1
• Java 21
• HSQLDB 2.7.2

HSQLDB の概要

HSQLDB にはカタログと呼ばれるデータの保存場所が３種類ある。

カタログ	JDBC URL	説明
mem:	jdbc:hsqldb:mem:mymemdb	メモリー上に格納される DB。永続化しない。
file:	インプロセス： jdbc:hsqldb:file:/opt/db/testdb サーバーモード： jdbc:hsqldb:hsql://localhost/xdb jdbc:hsqldb:http://localhost/xdb	ファイルに格納される DB。インプロセス以外に RDBMS を介するサーバーモードがある。RDBMS には独自プロトコルのものと HTTP のものがある（TLS もサポート。）。
res:	jdbc:hsqldb:res:db/testdb	Jar などの Java リソースに格納される DB。読み取り専用。

以下はそれぞれのイメージ。

インストール

公式サイトからダウンロードした Zip ファイルを解凍して任意の場所に置けば OK。最低限必要なのは hsqldb/lib 配下にある hsqldb.jar のみ。この jar に以下が含まれている。

• RDBMS エンジン
• JDBC ドライバー
• DB 管理ツール

データベースの作成

データベースを作成するには JDBC で file:カタログ（インプロセス）にアクセスする^[1]か、RDBMS を起動する。例えばjdbc:hsqldb:file:/opt/db/testdbにアクセスした場合/opt/db配下に以下のようなファイル群が生成される（データベースの状態によっては存在しないファイルもあり。）。

• testdb.properties
• testdb.script
• testdb.log
• testdb.data
• testdb.backup
• testdb.lobs

上記ファイルを Java リソースにコピーすることで res:カタログとしてアクセス可能。

データベースの終了

データベースを安全に終了するにはデータベースに接続してSHUTDOWNを実行する。

RDBMS の起動

以下のいずれかのクラスで RDBMS を起動することで file:カタログ（サーバーモード）でアクセスすることが出来る。

• org.hsqldb.server.Server（独自プロトコル）
• org.hsqldb.server.WebServer（HTTP）

実行例は以下の通り。--database.0オプションでパスを指定し--dbname.0オプションで DB 名を指定する。（--helpオプションで全てのオプションの説明が表示される。）

java -cp hsqldb.jar org.hsqldb.server.Server \
    --database.0 file:~/sample/db \
    --dbname.0 sampledb

DB 管理ツールの起動

以下のようにorg.hsqldb.util.DatabaseManagerSwingクラスを実行することで DB 管理ツール（GUI）が起動する。（--helpオプションで全てのオプションの説明が表示される。）

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

Connect ダイアログに接続情報を入力することで DB に接続する。file:カタログ（サーバーモード）の入力例は以下の通り。

項目名	入力値
Setting Name	sampledb
Type	HSQL Database Engine Server
Driver	org.hsqldb.jdbc.JDBCDriver
URL	jdbc:hsqldb:hsql://localhost/sampledb
User	SA
Password

脚注

1. jdbc:hsqldb:file:/opt/db/testdb;ifexists=trueのように URL にifexists=trueを付加した場合はデータベースが存在しないとエラーになる。