Using Liquibase with VoltDB

Image of Julius Krah 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

Tutorial

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

  1. Install the JDBC driver.

You can place the JDBC driver in the Liquibase/lib install directory so that it will automatically be located when executing Liquibase commands. Also, you can use another directory and add the location to the classpath in the liquibase.properties file.

  1. Install the Liquibase extension.

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

  1. Create a project folder.

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

  1. Create the liquibase.properties file in the project folder.

Note: If you are not familiar with configuring the liquibase.properties file, see Creating and configuring a liquibase.properties file tutorial.

The liquibase.properties file should contain the following properties:

changeLogFile: 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 your jdbc driver file in the Liquibase/lib install directory, there is no need to specify the classpath property in the liquibase.properties file. Otherwise, put the path to your drivers 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 liquibase.properties file:
liquibaseProLicenseKey: <paste license key>
  1. 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" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd 
http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.4.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>
  1. 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 updateSQL

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

liquibase update
  1. 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 tracking 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 tracking 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 changeset.

See also