Using Liquibase with CockroachDB
The purpose of this document is to guide you through the process of creating a new Liquibase project with CockroachDB. 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 CockroachDB.
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://jdbc.postgresql.org/download.html to download the PostgreSQL jdbc jar driver file to connect to CockroachDB.
Note: Place your jar file in the Liquibase/lib
install directory or in any other known directory so you can locate it easily.
- Generate TLS certificates for the user that you created during a secure CockroachDB cluster setup. Use the
cockroach cert
command to generate the certificates:
cockroach cert create-client user --certs-dir=certs --ca-key=my-safe-directory/ca.key --also-generate-pkcs8-key
Tutorial
To create a Liquibase project with CockroachDB, perform the following steps:
- Create a new project folder and name it
LiquibaseCockroachDB
. - In your
LiquibaseCockroachDB
folder, create a new text file and name itliquibase.properties
. - Edit the
liquibase.properties
file to add the following properties:
CockroachDB on-premises sample liquibase.properties
file
changeLogFile: dbchangelog.xml
url:jdbc:postgresql://localhost:26257/database?ssl=true&sslmode=require&sslrootcert=/full-path/certs/ca.crt&sslkey=/full-ath/certs/client.user.key.pk8&sslcert=/full-path/certs/client.user.crt
username: user1
password: password
driver: org.postgresql.Driver
classpath: ../../Liquibase_Drivers/postgresql-42.2.8.jar
When using the CockroachDB on-premises and specifying URL, enter your IP address or host name, and then the port followed by the database name. The example of the format is the following: jdbc:postgresql://<IP OR HOSTNAME>:<PORT>/<DATABASE>
.
The SSL connection parameters to the full paths of the certificates that you generated are optional.
A key in PKCS#8
format is the standard key encoding format in Java.
CockroachDB cloud sample liquibase.properties
file
changeLogFile: dbchangelog.xml
url: jdbc:postgresql://liquibase-3r8.aws-us-east-2.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=liquibase-ca.crt
username: user1
password: password
driver: org.postgresql.Driver
classpath: ../../Liquibase_Drivers/postgresql-42.2.8.jar
When using the CockroachCloud instance and specifying URL, enter a global host name and the port 26257
by referring to the CockroachCloud website. Also, add the database name with the SSL mode and the path to the CA certificate to your URL.
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
LiquibaseCockroachDB
folder, create a new text file and name itdbchangelog.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
andid
. Liquibase attempts to execute each changeset in a transaction that is committed at the end. In thedbchangelog.xml
file, add a newdepartment
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 public.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
LiquibaseCockroachDB
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 "public"."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.