1.1 簡介
hsqldb.jar 包位於/lib 目錄下，它包含了一些組件和程序。每個程序需要不同的命令來運行。
Hsqldb.jar 包中有下列這些組件：
• HSQLDB RDBMS
• HSQLDB JDBC Driver
• Database Manager (Swing and AWT versions)
• Transfer Tool (AWT version) ）
• Query Tool (AWT)
• Sql Tool (command line)
其中、HSQLDB RDBMS 和JDBCDriver 提供了HSQLDB 的核心功能。其餘的組件都是通
用的數據庫工具。這些通用工具可以使用在任何帶有JDBC 驅動的數據庫上。
1.2 運行工具
Hsqldb 提供的所有工具都能以java class 歸檔文件(也就是jar)的標準方式運行。在下面運行
AWT 版本的DatabaseManager 的例子中，hsqldb.jar 位於相對於當前路徑的../lib 下面。
java -cp ../lib/hsqldb.jar org.hsqldb.util.DatabaseManager
如果 hsqldb.jar 位於當前路徑中，運行DatabaseManager 的命令就應該改成：
java -cp hsqldb.jar org.hsqldb.util.DatabaseManager
Hsqldb 提供的主要的工具類
• org.hsqldb.util.DatabaseManager
• org.hsqldb.util.DatabaseManagerSwing
• org.hsqldb.util.Transfer
• org.hsqldb.util.QueryTool
• org.hsqldb.util.SqlTool
其中像DatabaseManager 或Sql Tool 這樣的工具，可以或者只能用命令行參數來運行。你
可以在命令行後面加上參數-?來查看這些工具可用的參數列表。Database Manager 和
Transfer Tool 具有圖形用戶接口，可以進行方便的交互式操作。
1.3 運行Hsqldb
HSQLDB 可以採用幾種不同的方式運行。一般可以分爲Server 模式和In-Process(進程內模
式,也稱之爲Standalone(獨立)模式）。對於每種模式，Jar 中都有相應的子程序來運行
HSQLDB。
每個 HSQLDB 數據庫包含了2 到5 個命名相同但擴展名不同的文件，這些文件位於同一個
目錄下。例如，名爲“test”的數據庫包含了以下幾個文件：
• test.properties
• test.script
• test.log
• test.data
• test.backup
properties 文件描述了數據庫的基本配置。 script 文件記錄了表和其它數據庫對象的定義，
此外還有non-cached（無緩衝）表的數據。log 文件記錄了數據庫最近所做的改動。data 文
件包含了cached（緩衝）表的數據，而backup 文件是將最後一次已知的連續狀態的data
文件以zip 方式壓縮備份。所有這些文件都是必不可少的，千萬不可擅自刪除。但如果你
的數據庫沒有緩衝表(cached table),test.data 和test.backup 文件就不會存在。此外，HSQLDB
數據庫可以鏈接到磁盤上任何地方任何格式化的文本文件，比如CSV 列表。
“test”數據庫在運行時， “test.log”文件是用來記錄數據的變化，在HSQLDB 正常關閉的時
候會被刪除。如果在非正常退出時，“test.log”將用來在下次啓動HSQLDB 時重複執行記錄
的更新操作. “test.lck”文件也可以用來記錄數據庫是否被打開，它在HSQLDB 正常退出的
時候會被刪除。有些情況下，HSQLDB 會生成test.data.old ”文件，但隨後會被刪除掉。
注意
當 HSQLDB 引擎關閉數據庫的時候，它會產生擴展名爲.new 的臨時文件，然後會把這些
文件重命名爲上面所列出的文件的名稱。
1.4 Server 模式
Server 模式提供了最好的訪問性能（accessibility）。數據庫引擎在JVM 裏運行，監聽來自
同一臺計算機上或網絡中其他計算機程序的連接請求。幾個不同的程序可以連接到服務器
並且查詢和更新信息。應用程序（客戶端）通過HSQLDB 的JDBC Driver 連接服務器。在
大多數的服務器模式中，服務器可以在運行的時候被指定爲最多10 個數據庫服務。
服務器模式可以預置屬性和命令行參數，詳見“高級主題”一章。根據客戶端和服務器之間
通信協議的不同，Server 模式可以分爲以下三種：
庫的服務器，這個數據庫是一個名爲"mydb.*"文件。
java -cp ../lib/hsqldb.jar org.hsqldb.Server -database.0 file:mydb -dbname.0 xdb
命令行參數-?可以用來查看該命令的可用參數列表。
1.4.2 Hsqldb Web Server
這種模式用在只能通過HTTP 訪問啓用數據庫服務的計算機的情況下。採用Web Server 模
式的唯一原因是客戶端或服務端的防火牆對網絡連接訪問採取了限制。其他情況下，這種
模式不推薦被使用。HSQLDB Web Server 是可以允許JDBC 客戶端通過HTTP 連接的特殊
Web Server。從1.7.2 版本開始，這種模式也支持事務處理。
運行 web server 的時候，只要將上例命令行中Server 的主類（main class）替換爲下面的類：
org.hsqldb.WebServer
命令行參數-?可以用來查看該命令的可用參數列表。
1.4.3 Hsqldb Servlet
這種模式和Web Server 一樣都採用HTTP 協議，當如Tomcat 或Resin 等單獨的servlet 引
擎（或應用服務器）提供數據庫訪問時，可以使用這種模式。但是Servlet 模式不能脫離servlet
引擎獨立啓動。爲了提供數據庫的連接，應該將HSQLDB.jar 中的Servlet 類安裝在應用服
務器上（放置在library 目錄下）。可以使用應用服務器的的屬性來指定數據庫，可以參考
org.hsqldb.Servlet.java 的源文件查看詳細信息。
Web Server 和Servlet 模式在客戶端都只能通過JDBC 驅動來訪問。兩者都不提供數據庫的
web 前臺終端(front end)。Servlet 模式只能啓動一個單獨的數據庫。
請注意在應用服務器中使用數據庫引擎通常不採用這種模式。
連接以 Server 模式運行的數據庫
當 HSQLDB Server 運行時，客戶端程序就可以通過hsqldb.jar 中帶有的HSQLDB JDBC
Driver 連接數據庫。如何連接服務器的詳細說明可以參見jdbcConnection 的Java 文檔
[../src/org/hsqldb/jdbc/jdbcConnection.html]（位於HSQLDB 發佈包/doc/src 目錄中）。下面是一
個簡單的例子，它採用hsqldb 協議連接到本機的默認的9001 端口。
Example 1.1. Java code to connect to the local Server above
try {
Class.forName("org.hsqldb.jdbcDriver" );
} catch (Exception e) {
System.out.println("ERROR: failed to load HSQLDB JDBC driver.");
e.printStackTrace();
return;
}
Connection c = DriverManager.getConnection("jdbc:hsqldb:hsql://localhost/xdb", "sa", "");
有些情況下，你也可以使用下面的代碼來獲取驅動(driver).
Class.forName("org.hsqldb.jdbcDriver").newInstance();
可以注意到，在上面的鏈接中，沒有提到數據庫文件，因爲這些在Server 運行時，數據庫
文件就已經被指定爲dbname.0 的值了。對於每個server 不止有一個數據庫實例情況的連接
URL 也可以閱讀“高級主題”一章。
安全因素的考慮
HSQLDB 以Server 模式運行的時候，網絡訪問應該受到充分的保護。源IP 地址可能會因
爲TCP 過濾、防火牆程序或者獨立的防火牆的使用，而受到限制。如果數據流要穿越一個
不受保護的網絡（比如Internet 時），數據流應該被加密（比如採用VPN，SSH 隧道或者
TLS）。只有安全的密碼纔可以使用——最重要的是，應該將爲系統默認用戶設置的空字符
串密碼修改爲安全密碼。如果你想公開自己的數據的話，那麼完全開放的網絡連接應該限
製爲只有通過只讀的帳號來訪問這些公開的數據。（比如，對於非機密數據或非特權用戶可
以考慮使用這種連接方式）。這些考慮因素也適用於採用HTTP 協議運行HSQLDB 服務器
的情況下。
1.4.4 In-Process(Standalone)模式
這種模式下，數據庫引擎作爲應用程序的一部分在同一個JVM 中運行。對於一些應用程序
來說， 這種模式因爲數據不用轉換和通過網絡的傳送而使得速度更快一些。其主要的缺點
就是默認不能從應用程序外連接到數據庫。所以當應用程序正在運行的時候，你不能使用
類似於Database Manager 的外部工具來查看數據庫的內容。在1.8.0 版本中，你可以從同一
個JVM 的一個線程裏面來運行一個服務器實例作爲您的應用程序，從而可以提供外部連接
來訪問你的In-Process 數據庫。
在一個應用程序裏，推薦使用 In-Process 模式的方式是：開發的時候爲數據庫使用一個
HSQLDB 服務器實例，然後在部屬的時候切換到In-Process 模式。
一個In-Process 模式數據庫是使用JDBC，帶有指定數據庫文件路徑的連接URL 來啓動的。
例如，假如數據庫名稱爲testdb，它的數據庫文件位於和相關運行應用程序命令相同的目
錄下，下面的代碼可以用於數據庫的連接：
Connection c = DriverManager.getConnection("jdbc:hsqldb:file:testdb", "sa", "");
數據庫文件的路徑格式在 Linux 主機和Windows 主機上都被指定採用前斜線(”/”）。所以
相對路徑或相對於相同分區下相同目錄路徑的表達方式是一致的。例如，在Linux 系統中
你的數據庫文件路徑爲/opt/db/testdb，你可以在Windows 的C:分區下，創建一個相同的目
錄結構，然後你可以在Linux 和Window 下采用相同的URL：
Connection c = DriverManager.getConnection("jdbc:hsqldb:file:/opt/db/testdb", "sa", "");
使用相對路徑的時候，這些路徑表示的是相對於用於啓動 JVM 的shell 命令的路徑。你可
以參考jdbcConnection 的Java 文檔[../src/org/hsqldb/jdbc/jdbcConnection.html]來獲得更多詳細
信息。
1.4.5 Memory-Only 數據庫
HSQLDB 還可以用這種方式運行——數據庫不是持久化的而是全部在隨機訪問的內存中。
因爲沒有任何信息寫在磁盤上，所以這種模式應該用於應用數據的內部處理上，比如在
applet 或其他的一些特殊的應用程序中。這種模式通過mem: protocol 的方式來指定：
Connection c = DriverManager.getConnection("jdbc:hsqldb:mem:aname", "sa", "");
你也可以在 server.properties 中指定相同的URL 來運行一個Memory-Only（僅處於內存中）
服務器實例。這種用法不常用，盡限於在使用數據庫服務器來交換兩個客戶端的數據或者
是非持久化數據的特殊應用程序中使用。
1.5 一般操作
1.5.1 關閉數據庫
以不同模式運行的所有數據庫都可以通過以 SQL 語句發出的SHUTDOWN 命令來關閉。
從1.7.2 版本以後，當最後一次的數據庫的連接通過JDBC 被顯式關閉之後，in-process 模
式的數據庫將不再被關閉，除非使用SHUTDOWN 命令。在1.8.0 中，可以在第一次第一
次打開數據庫的連接中，指定shutdown=true 這個連接屬性，在最後一次鏈接關閉時，強
制關閉數據庫。
當 SHUTDOWN 命令發出，所有的活動事務（active transactions）都會被回滾（rolled back）。
關閉數據庫的一種特殊形式是通過SHUTDOWN COMPACT 命令。該命令重寫.data 文件，
這個文件包含了存儲在CACHED 表中的信息，該命令對該文件的大小進行精簡(compact)。
這個命令應該被週期性執行，特別是在cached 表中執行了許多插入，更新和刪除操作的時
候。數據庫結構的變換，比如刪除、更改CACHE 表或者索引，會產生大量未使用的文件
空間，不過可以通過此命令進行空間的回收利用。
1.5.2 在一個JVM 裏使用多個數據庫
在上述的例子中，每個服務器只有一個數據庫工作以及僅能創建一個 In-Memory 數據庫。
不過，從1.7.2 版本以後，HSQLDB 能夠以多個服務器模式使用多個數據庫，它允許對多
個In-Process 數據庫和memory-only 數據庫進行併發訪問。這些性能在“高級主題”一章進
行了敘述。
1.5.2 創建新數據庫
當一個服務器實例啓動或者建立一個 in-process 數據庫連接時，如果指定的路徑沒有數據
庫存在，那麼就會創建一個新的空數據庫。
這個特性的副作用就是讓那些新用戶產生疑惑——在指定連接到已存在的數據庫路徑時，
如果出現了什麼錯誤的話，仍然會創建一個指向新數據庫的連接。爲了解決這個問題，你
可以指定一個連接屬性ifexists=true 只允許和已存在的數據庫建立連接而避免創建新的數
據庫，如果數據庫不存在的話，getConnection()方法將會拋出異常。
1.6 使用數據庫引擎
一旦以任何模式建立了數據庫的連接，就可以使用JDBC 方法和數據庫交互。對於
jdbcConnection[../src/org/hsqldb/jdbc/jdbcConnection.html], ,
jdbcDriver[../src/org/hsqldb/jdbcDriver.html],
jdbcDatabaseMetadata[../src/org/hsqldb/jdbc/jdbcDatabaseMetaData.html],jdbcResultSet[../src/org/
hsqldb/jdbc/jdbcResultSet.html], jdbcStatement[../src/org/hsqldb/jdbc/jdbcStatement.html], 和
jdbcPreparedStatement[../src/org/hsqldb/jdbc/jdbcPreparedStatement.html]的JavaDoc 列出了所
有支持的JDBC 方法以及對HSQLDB 的詳細說明信息。JDBC 方法大體上可以分爲：與連
接相關的方法，元數據方法，數據庫訪問方法三種。數據庫訪問方法使用SQL 命令來在數
據庫上執行操作，返回的結果既可以是Java 原型（Primitive）數據類型，也可以是
java.sql.ResultSet 類的實例。
你可以使用 Database Manager 或者其他Java 數據庫訪問工具來查看數據庫的內容，並可以
用SQL 命令來更新數據庫。這些程序在內部使用JDBC 向數據庫引擎提交你的命令，並用
自然語言的格式來顯示結果。
HSQLDB 中使用的SQL 方言（dialect）與SQL92 和SQL200n 標準比較接近，到目前位置
HSQLDB 在小型數據庫引擎中已經有可能這兩個標準。“SQL 語法”一章列出了所有的SQL
命令。
1.6.1 不同的表類型
HSQLDB 支持臨時表和三種持久化表。
TEMP（臨時）表是不寫入磁盤，它僅僅只維持一個Connection對象的生命週期。每一個TEMP
表僅對操作它的Connection來說是可見的，其他和數據庫併發的連接只能訪問自己的TEMP
表備份。從1.8.0版本開始， TEMP表的定義遵循SQL標準的GLOBAL TEMPORARY
類型。表的定義是持久的，但每個新的連接只能看到它自己的表，而這些表剛開始是空的。
當連接提交以後，臨時表裏的內容默認會被清空。如果臨時表的定義語句裏邊包括ON
COMMIT PRESERVE ROWS,那麼當連接提交發生時，臨時表的內容將被保存。
三種類型的持久化表一次是 MEMORY（內存）表，CACHED（緩存）表和TEXT（文本
符）表。
Memory 表是使用CREATE TABLE 命令的默認表類型。Memory 表數據全部駐留在內存中，
但是對於表結構或內容的任何修改都被寫入到<dbname>.script 文件中。script 文件在下次數
據庫打開的時候被MEMORY 讀取，裏邊的所有內容在MEMORY 表中重新創建。所以跟
TEMP 表不同， MEMORY 表被默認爲是持久的。
CACHED 表是在使用CREATE CACHED TABLE 命令的時候生成的。它只有索引或部分
數據是駐留在內存中的，所以可以允許生成大容量表而不用佔用幾百兆的內存。CACHED
表的另外一個優點，即使它存儲了大量的數據，數據庫引擎只需花費很短的時間就可以啓
動。它的不足是在速度上有所降低。如果你的數據集相對小的時候，儘量不要使用CACHED
表。在小容量和大容量表共存的實際應用中，最好對小容量的表使用默認的MEMORY 表。
TEXT 表是在1.7.0 版本中開始支持的，它使用CSV（逗號分割數值）或其他分隔符的文本
文件作爲數據源。你可以指定一個已有的CSV 文件（比如其它數據庫或程序導出的數據）
作爲TEXT 表的數據源，你也可以指定一個空文件用數據庫引擎來填充數據。TEXT 表的
內存利用效率比較高，因爲它只緩存部分文本數據和所有的索引。TEXT 表的數據源如果
需要的話，可以重新分配到不同的文件。建立一個TEXT 表所需的兩個命令的詳細資料請
查看TEXT 表一章。
在 Memory-Only 數據庫裏，MEMORY 表和CACHED 表的聲明都看視作爲非持久化的內
存表聲明。這種模式中是不允許聲明TEXT 表的
1.6.2 約束和索引
HSQLDB 支持PRIMARY KEY, NOT NULL, UNIQUE, CHECK 和FOREIGN KEY（依次譯
作主鍵、非空、唯一性、檢查、外鍵）約束。此外，它還支持唯一性索引或普通索引。這
些支持相當廣泛，覆蓋了多字段約束和索引，再加上外鍵的級聯更新和刪除。
HSQLDB 在內部創建索引來支持主鍵約束、唯一性約束和外鍵約束：爲每一個主鍵約束或
唯一性約束創建一個唯一索引，爲每個外鍵約束創建一個普通的索引。因爲這些原因，你
不應該在受這些約束的同一字段集內創建重複的用戶自定義索引。這將會導致不必要的內
存和速度開支。你可以查看“SQL 問題”一章的討論來獲得更多的信息。
索引對於提高查詢速度是至關重要的，當使用連接到多個表的查詢時，對於每一個表的每
一個連接字段必須有一個索引。當使用範圍或等式從句（比如：SELECT ... WHERE acol >10
AND bcol = 0）時，需要爲在條件中使用的acol 列創建一個索引。但是索引在ORDER BY
從句或某些LIKE 條件中是沒有任何作用的。
根據經驗，HSQLDB 能夠以超過每秒100,000 行的能力來處理查詢，如果需要的話，任何
花費數秒以上的查詢應該被檢查，並且應該對錶中相應的列添加索引。
1.6.3 SQL 支持
HSQLDB 支持的SQL 語法主要是由SQL 標準（92 和200n）規定的。但HSQLDB 也不是
支持標準的所有特性，還有一些自己特有的擴展，在1.8.0 版本中，數據庫引擎比老版本能
更好的遵循標準，其主要的改變有：
• 修正了在連接、唯一性約束或是在查詢條件中的空列值的處理。
• 修正了採用連接和左外連接 select 的處理。
• 修正了包含在表達式或包含表達式參數的聚集函數的處理。
HSQLDB 所支持的命令都列舉在“SQL 語法”一章。你可查看由Bruce Momjian 寫的
PostgreSQL: Introduction and Concepts 一章，它是一部不錯的SQL 基本指南，並且帶有樣
例，你可以點擊鏈接下載。書中所講到的大多數SQL 都可以用到HSQLDB 中。但是在數
據庫引擎支持的關鍵字（OUTER, OID's 等）和使用不同的關鍵字上（IDENTITY/ SERIAL,
TRIGGER, SEQUENCE 等）存在着一些差異。
1.6.4 JDBC 支持
在 1.7.2 版本中，對於JDBC2 的支持已經取得了重大的進展，而且現在已經開始支持JDBC3
的部分特徵。相關的類都已經文檔化了， 你可以查看org.hsqldb.jdbcXXXX 類的
JavaDoc[../src/index.html]獲得幫助。