HSQLDB 持久化建置完整指南：命令列、工具類與 Ant 整合

前言

HSQLDB（HyperSQL DataBase）是純 Java 撰寫、極輕量且效能優異的關聯式資料庫，廣泛用於單元測試、嵌入式應用與快速原型開發。本文系統整理 HSQLDB 的持久化模式、命令列操作、內建工具類，並示範如何以 Ant 實現持續整合建置流程。

核心資料庫模式

常用內建工具類（均在 hsqldb.jar 中）

• org.hsqldb.util.DatabaseManager：字元介面管理工具
• org.hsqldb.util.DatabaseManagerSwing：Swing 圖形化管理工具
• org.hsqldb.util.Transfer：資料遷移/匯出入
• org.hsqldb.util.QueryTool：互動式查詢工具
• org.hsqldb.util.SqlTool：批次執行 SQL 腳本、產生報表的核心工具

啟動範例：java -cp hsqldb.jar org.hsqldb.util.DatabaseManagerSwing

持久化檔案結構

預設資料庫名稱 test 會產生五個檔案：

• test.properties：屬性設定
• test.script：DDL/DML 腳本日誌（核心資料）
• test.log：交易日誌
• test.data：CACHED 資料表資料
• test.backup：備份壓縮檔

Server 模式啟動範例

# 1. 進入 HSQLDB 目錄
cd F:\temp\hsqldb

# 2. 啟動預設 test 資料庫
java -classpath ./lib/hsqldb.jar org.hsqldb.Server
# 產生 test.lck, test.log, test.properties

# 3. 指定資料庫檔案名與別名
java -classpath ./lib/hsqldb.jar org.hsqldb.Server -database.0 adb -dbname.0 adb
# 產生 adb.lck, adb.log, adb.properties
# 連線 URL: jdbc:hsqldb:hsql://localhost/adb

# 4. 指定資料庫存放子目錄
java -classpath ./lib/hsqldb.jar org.hsqldb.Server -database.0 data/adb -dbname.0 adb
# 在 data/ 目錄下建立檔案，連線 URL 不變

SqlTool 執行 SQL 腳本（需 sqltool.rc 驗證）

在使用者家目錄建立 sqltool.rc：

urlid localhost-sa
url jdbc:hsqldb:hsql://localhost/
username sa
password

命令列執行單條/多條 SQL

java -jar ./lib/hsqldb.jar --sql "INSERT INTO t VALUES(1); SELECT * FROM t;" localhost-sa

執行 SQL 檔案（支援特殊指令）

java -jar ./lib/hsqldb.jar localhost-sa sample.sql

sample.sql 關鍵指令：

• \c true/false：錯誤是否繼續執行
• \p 訊息：列印進度訊息
• \o report.txt：導出查詢結果至文字檔
• \H：切換 HTML 格式報表輸出
• COMMIT;：手動提交交易（預設不自動提交）

關閉 Server

java -jar ./lib/hsqldb.jar --sql "SHUTDOWN" localhost-sa

Ant 整合持續建置範本

<project name="hsqldb-build" basedir="." default="help">
  <property name="hsqldb.path" value="lib/hsqldb.jar"/>
  <property name="database.dir" value="db"/>
  <property name="database.name" value="appfuse"/>
  <property name="database.urlid" value="localhost-sa"/>

  <target name="startServer" description="啟動 HSQLDB Server">
    <java classname="org.hsqldb.Server" classpath="${hsqldb.path}" fork="true" failonerror="true">
      <arg value="-database.0"/> <arg value="file:${database.dir}/${database.name}"/>
      <arg value="-dbname.0"/>  <arg value="${database.name}"/>
    </java>
  </target>

  <target name="shutdownServer" description="關閉 Server">
    <java jar="${hsqldb.path}" classpath="${hsqldb.path}" fork="true" failonerror="true">
      <arg value="--sql"/> <arg value="shutdown"/> <arg value="${database.urlid}"/>
    </java>
  </target>

  <target name="populate" description="匯入範例資料">
    <java jar="${hsqldb.path}" classpath="${hsqldb.path}" fork="true" failonerror="true">
      <arg value="${database.urlid}"/> <arg value="src/org/hsqldb/sample/sampledata.sql"/>
    </java>
  </target>

  <target name="report" description="產生 HTML 報表">
    <mkdir dir="report"/>
    <java jar="${hsqldb.path}" classpath="${hsqldb.path}" fork="true" failonerror="true">
      <arg value="${database.urlid}"/> <arg value="querydata.sql"/>
    </java>
  </target>

  <target name="clean" description="清理輸出">
    <delete dir="report"/>
  </target>
</project>

執行流程：ant startServer populate report shutdownServer 即可完成資料庫啟動、資料載入、報表產生、關閉的完整自動化流程。

結語

掌握 HSQLDB 的多種模式、命令列工具與 Ant 整合，能讓測試環境建置、資料遷移、報表產出全自動化，極大提升團隊開發效率與 CI/CD 可靠度。