Using Liquibase with HSQLDB

The purpose of this document is to guide you through the process of creating a new Liquibase project with HyperSQL Database (HSQLDB). In this tutorial, you will learn how to install the required database drivers and configure the file to establish a database connection to HSQLDB.


Note: Liquibase comes with a pre-installed driver for HSQLDB in the liquibase/lib directory. For more information, see Adding and Updating Liquibase Drivers.


To create a Liquibase project with HSQLDB, perform the following steps:

  1. Create a new project folder and name it LiquibaseHSQLDB.
  2. In your LiquibaseHSQLDB folder, create a new text file and name it

Note: For more information about the file, see Creating and configuring a file.

  1. Edit the file to add the following properties:
changeLogFile: dbchangelog.xml
url: jdbc:hsqldb:hsql://
username: user
password: password
driver: org.hsqldb.jdbcDriver
classpath: ../../Liquibase_Drivers/hsqldb.jar

Note: Specifying your password, take into account that Liquibase supports only the following special characters: ~ # $ % * ( ) - _ + [ ] { } . ?. Unsupported special characters are as follows: @ & / : < > " ' ` | ^ ! = , \ <spaces>.

Use the following format for the url property:


Note: As an HSQLDB database can be run in two modes—standalone and server, the url property formats differ. The standalone mode runs the database engine as part of your application program, and the software runs in the same local thread. If you use the standalone mode of HSQLDB, follow this format of the url property:

  • If you placed your jdbc driver file in the liquibase/lib install directory, there is no need to specify the classpath property in the file. Otherwise, put the path to your driver as it is shown in the preceding example.
  • If you already have a Liquibase Pro key and want to apply it to your project, add the following property to your file:
liquibaseProLicenseKey: <paste license key>
  1. Create a changelog file. The changelog files contain a sequence of changesets, each of which makes small changes to the structure of your database. For more information, see Working with Changelogs . Liquibase provides a changelog template located at $LIQUIBASE_HOME/examples/xml/blank.changelog.xml. Copy the blank.changelog.xml file to your LiquibaseHSQLDB folder and rename it to dbchangelog.xml. Each version of Liquibase will have an updated XML schema, so use the one that matches the version of Liquibase you have installed. The contents of the changelog will be similar to the following:
  1. Verify the project configuration. Run the status command to verify that the configuration is complete. Open a command prompt and navigate to the project folder LiquibaseHSQLDB. Run the command as follows:
liquibase status
  1. Verify that the DATABASECHANGELOG and DATABASECHANGELOGLOCK tables were created. From a database UI tool, check your new Liquibase tables.

After your first update, your database will contain the table you added along with the DATABASECHANGELOG and DATABASECHANGELOGLOCK tables:

  • DATABASECHANGELOG table. This table keeps a record of all the changesets that were deployed. When you deploy, the changesets in the changelog are compared with the DATABASECHANGELOG tracking table, and only the new changesets that were not found in the DATABASECHANGELOG will be deployed.
  • DATABASECHANGELOGLOCK table. This table is used internally by Liquibase to manage access to the DATABASECHANGELOG table during deployment and ensure only one instance of Liquibase is updating the database at a time, whether that is creating, updating, or deleting changes.


You have successfully configured your project and can begin creating changesets to migrate changes to your database. For more information on how to create changesets, see Changelog Formats .

See also