Using Liquibase with VoltDB

Written by: Pavan Mulani

The purpose of this document is to guide you through the process of creating a new Liquibase project for VoltDB. In this tutorial, you will learn how to install the required database drivers and configure the Liquibase properties file to establish a database connection to VoltDB.

Support for VoltDB is provided via a Liquibase extension. The extension provides basic database operations including:

DML statements
DDL statements

Prerequisites

Before using Liquibase with your database, ensure you have:

Installed Liquibase.
Created a Liquibase project folder to store all Liquibase files.
Created a new Liquibase properties file or are using the existing liquibase.properties file included in the installation package. For more information, see Specifying Properties in a Connection Profile.

Note: We will refer to the location of the Liquibase executable as $LIQUIBASE_HOME in this tutorial.

Download the VoltDB JDBC driver.
Download the Liquibase extension for VoltDB.

Note: If you use Maven, reference the dependency extension .jar file locally. For more information, see Configuring Liquibase Attributes in your Maven POM File.

Tutorial

To configure a Liquibase project for VoltDB, perform the following steps:

Install the JDBC driver.

If you place the JDBC driver in the liquibase/lib install directory, it is loaded automatically when running Liquibase commands. Also, you can use another directory and add the location to the classpath in the Liquibase properties file.

Install the Liquibase extension.

Copy the extension jar file into the $LIQUIBASE_HOME/lib directory.

Create a project folder.

The project folder will be used to store the Liquibase configuration files and changelogs.

Add the following properties to the Liquibase properties file:

changelog-file: dbchangelog.xml 
url: jdbc:voltdb://10.151.33.71:21212 
username: voltdb 
password: voltdb 
driver: org.voltdb.jdbc.Driver 
classpath: ../../Liquibase_Drivers/jdbcdriver.jar

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

Use the following format for the url property:

jdbc:voltdb://<server>:<port>

If you placed the jdbc driver file in the liquibase/lib install directory, do not specify the classpath property in the Liquibase properties file. Otherwise, specify the driver path as shown in the preceding example.
To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file:

liquibaseProLicenseKey: <paste license key>

Create a dbchangelog.xml file in the project folder.

Add a changeset to the changelog. The changesets are uniquely identified by author and id. Liquibase attempts to execute each changeset in a transaction that is committed at the end. In the dbchangelog.xml file, add a new department create table changeset as follows:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
	xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
	xmlns:pro="http://www.liquibase.org/xml/ns/pro"
	xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
		http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.9.xsd
		http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
		http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-4.9.xsd">
<createTable  tableName="person">
      <column  name="id"  type="int"  autoIncrement="true">
            <constraints  primaryKey="true"  nullable="false"/>
      </column> 
      <column  name="firstname"  type="varchar(50)"/>
      <column  name="lastname"  type="varchar(50)">
            <constraints  nullable="false"/>
      </column>
  </createTable>
  </changeSet>

<changeSet author="authorname" id="insert-example"> 
      <insert tableName="person">
      <column name="id" value="1"/>
      <column name="firstname" value="Bob"/>
      <column  name="lastname"  value="Builder" />
      </insert>
</changeSet>
</databaseChangeLog>

Generate and execute SQL

Open the command prompt, navigate to the project directory, and then run the following command to get the SQL output of the changelogs:

liquibase update-sql

To execute the changeset in your schema, run the following:

liquibase update

Verify that the tables have been created

From a database UI Tool, check your database changes. You will see a new person and table added to the database. For example:

SELECT * FROM PERSON;

Also, you will see two more tables:

DATABASECHANGELOG table. This table keeps a record of all the changesets that were deployed. This way, when you deploy again, the changesets in the changelog will be compared with the DATABASECHANGELOG tracking table, and only the new changesets that were not found in the DATABASECHANGELOG will be deployed. You will see that a new row was created in that table with the changeset information you have just deployed. For example:

DATABASECHANGELOGLOCK table. This table is used internally by Liquibase to manage access to the changelog table during deployment.

Congratulations!

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.

Using Liquibase with VoltDB

Prerequisites

Tutorial

Congratulations!

See also