Using Liquibase with SAP HANA

The purpose of this document is to guide you through the process of creating a new Liquibase project with SAP HANA. In this tutorial, you will learn how to generate an example project and follow the instructions to apply concepts associated with creating new Liquibase projects with SAP HANA.

Prerequisites

Ensure that you have installed the latest version of Liquibase. If not, go to https://www.liquibase.org/download to install it.
Ensure the liquibase.bat file's path is set to a location in the PATH System variable.
Go to https://mvnrepository.com/artifact/com.sap.cloud.db.jdbc/ngdbc to download the jdbc jar driver file. If you used the SAP HANA client software package, the jdbc jar driver file is already installed as part of it.
Go to https://github.com/liquibase/liquibase-hanadb/releases to download the appropriate extension jar file. For more information, see SAP HANA Liquibase extension.

Place your jar files in the Liquibase/lib install directory or in any other known directory so you can locate it easily.

Note: If you use Maven, you also need to download the .jar file from the Maven repository. Additionally, specify the Liquibase extension in your pom.xml file by referring to Configuring Liquibase Attributes in your Maven POM File and make sure that the Liquibase plugin and the extension have the same version.

Tutorial

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

Create a new project folder and name it LiquibaseSAPHANA.
In your LiquibaseSAPHANA folder, create a new text file and name it liquibase.properties.
Edit the liquibase.properties file to add the following properties:

changeLogFile: dbchangelog.xml
            url: jdbc:sap://localhost:30013/?databaseName=mydatabase&encrypt=true
            username: user1
            password: password
            driver: com.sap.db.jdbc.Driver
            classpath: ../../Liquibase_Drivers/ngdbc-2.5.50.jar

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

If you placed your jar 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 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 liquibase.properties file:

liquibaseProLicenseKey: <paste license key>

In your LiquibaseSAPHANA folder, create a new text file and name it dbchangelog.xml. The changelog files contain a sequence of changesets, each of which makes small changes to the structure of your database.

Note: Instead of creating an empty changelog file, you can use an existing database to generate a changelog. In this tutorial, you will manually add a single change. To add this change, open the XML file and update the changelog file with the following code snippet:

<?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"
          xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
          http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd">
  /databaseChangeLog>

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"
       xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
              http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd">
           <changeSet id="1" author="bob">
             <createTable tableName="department">
                <column name="id" type="int">
                     <constraints primaryKey="true" nullable="false"/>
                </column>
                <column name="name" type="varchar(50)">
                      <constraints nullable="false"/>
                </column>
                <column name="active" type="boolean" defaultValueBoolean="true"/>
                </createTable>
             </changeSet>
</databaseChangeLog>

Note: The preceding changeset is XML format. The corresponding SQL statement looks like the following:

--liquibase formatted sql

--changeset bob:1
CREATE TABLE "DEPARTMENT" ("ID" INTEGER, "NAME" STRING, "ACTIVE" BOOLEAN);
--changeset bob:1
CREATE TABLE department (id INTEGER NOT NULL, 
name VARCHAR(50) NOT NULL, 
active BOOLEAN DEFAULT TRUE, 
CONSTRAINT DEPARTMENT_PKEY PRIMARY KEY (id));

Open the command prompt, navigate to the LiquibaseSAPHANA directory, and then run the following command:

liquibase update

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

SELECT * FROM "AA_HANA11"."department";

ID	Name	Active
NULL	NULL	NULL

Also, you will see two more tables:

DATABASECHANGELOG tracking table. This table keeps a record of all the changesets that were deployed. This way, next time 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 we have just deployed. For example:

ID	Author	Filename	Dateexecuted	Orderexecuted	Exectype	MDSum
1	bob	dbchangelog.xml	date&time	1	EXECUTED	checksumvalue

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

Using Liquibase with SAP HANA

Prerequisites

Tutorial

See also