Using Liquibase with DB2 for zOS

DB2 for z/OS is a relational database management system that runs on the mainframe. For more information, see IBM DB2 Documentation.

Supported Database Versions

11.5.7+

Prerequisites

  • Install Liquibase. For more information about downloading and installing Liquibase, see Installing Liquibase.
  • Confirm that you have purchased the DB2 Connect product and have an active DB2 license JAR file. This JAR file is required to connect to the mainframe DB2 database. For more information about locating your DB2 JCC JDBC driver JAR file, go to this article on IBM's documentation site.
  • For Liquibase Pro users, confirm that your license key is activated. For more information about activating your Liquibase Pro license key, see How to Apply Your Liquibase Pro License Key.

Download and Install Drivers

The latest version of Liquibase includes a driver for this database in the liquibase/internal/lib directory. If you're not using Maven, you do not have to download or install anything to use Liquibase with IBM DB2 for zOS.

To use Liquibase with Maven, complete the following steps:

  1. Download the JDBC driver JAR file (Maven download).
  2. Copy or move your JAR files into the liquibase/lib directory.
  3. Include include the driver JAR(s) as a dependency in your pom.xml file. Using this information, Maven automatically downloads the driver JAR from Maven Central when you build your project.you must install a local copy of the driver JAR(s) and add it as a dependency to your pom.xml file. This database does not provide its driver JAR on a public Maven repository.
<dependency>
    <groupId>com.ibm.db2</groupId>
    <artifactId>jcc</artifactId>
    <version>11.5.7.0</version>
</dependency>

Enable Liquibase Pro Capabilities

For Liquibase Pro users, add the following property to the Liquibase properties file.

liquibase.licenseKey: <paste key here>

Configure connection

  1. Confirm the configuration of the DB2 on z/OS database. Run the DISPLAY DATABASE command to display the status of DB2 databases.

  2. Specify the database URL in the liquibase.properties file (defaults file), along with other properties you want to set a default value for. Liquibase does not parse the URL. You can either specify the full database connection string or specify the URL using your database's standard connection format:
  3. url: jdbc:db2://<server_name>:<port>/<db_name>

Note: The URL for DB2 on z/OS may have different formats, such as jdbc:db2j:net:, jdbc:ibmdb:, and jdbc:ids:, depending on your connection type. For more information, see the URL format for the IBM Data Server Driver for JDBC and SQLJ type 4 connectivity.

Test connection

  1. Create a text file called changelog (.xml, .sql, .yaml, or .json) in your project directory and add a changeset.

    If you already created a changelog using the init project command, you can use that instead of creating a new file. When adding onto an existing changelog, be sure to only add the changeset and to not duplicate the changelog header.

  2. --liquibase formatted sql
    
    --changeset your.name:1
    CREATE TABLE test_table (test_id INT NOT NULL, test_column INT, PRIMARY KEY (test_id))

    Tip: Formatted SQL changelogs generated from Liquibase versions before 4.2.0 might cause issues because of the lack of space after a double dash ( -- ). To fix this, add a space after the double dash. For example: -- liquibase formatted sql instead of --liquibase formatted sql and -- changeset myname:create-table instead of --changeset myname:create-table.

    databaseChangeLog:
       - changeSet:
           id: 1
           author: your.name
           changes:
           - createTable:
               tableName: test_table
               columns:
               - column:
                   name: test_id
                   type: INT
                   constraints:
                       primaryKey:  true
                       nullable:  false
               - column:
                   name: test_column
                   type: INT
    {
      "databaseChangeLog": [
        {
          "changeSet": {
            "id": "1",
            "author": "your.name",
            "changes": [
              {
                "createTable": {
                  "tableName": "test_table",
                  "columns": [
                    {
                      "column": {
                        "name": "test_id",
                        "type": "INT",
                        "constraints": {
                          "primaryKey": true,
                          "nullable": false
                        }
                      }
                    },
                    {
                      "column": {
                        "name": "test_column",
                        "type": "INT"
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
    <?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-latest.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-latest.xsd">
    
        <changeSet id="1" author="your.name">
            <createTable tableName="test_table">
                <column name="test_id" type="int">
                    <constraints primaryKey="true" nullable="false" />
                </column>
                <column name="test_column" type="int"/>
            </createTable>
        </changeSet>
    
    </databaseChangeLog>
  3. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:
  4. liquibase status --username=test --password=test --changelog-file=<changelog.xml>

    Note: You can specify arguments in the CLI or keep them in the Liquibase properties file.

    If your connection is successful, you'll see a message like this:

    4 changesets have not been applied to <your_connection_url>
    Liquibase command 'status' was executed successfully.
  5. Inspect the deployment SQL with the update-sql command:
  6. liquibase update-sql --changelog-file=<changelog.xml>

    If the SQL that Liquibase generates isn't what you expect, you should review your changelog file and make any necessary adjustments.

  7. Then execute these changes to your database with the update command:
  8. liquibase update --changelog-file=<changelog.xml>

    If your update is successful, Liquibase runs each changeset and displays a summary message ending with:

    Liquibase: Update has been successful.
    Liquibase command 'update' was executed successfully.
  9. From a database UI tool, ensure that your database contains the test_table object you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

Now you're ready to start making deployments with Liquibase!

Related links