第1 章运行、使用 Hsqldb

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]获得帮助。