Get started with Liquibase and Neon

Liquibase is an open-source library for tracking, managing, and applying database schema changes. To learn more about Liquibase, refer to the Liquibase documentation.

This guide steps you through installing the Liquibase CLI, configuring Liquibase to connect to a Neon database, deploying a database schema change, and rolling back the schema change. The guide follows the setup described in the Liquibase Get Started.

Prerequisites

• A Neon account. See Sign up.
• A Neon project. See Create your first project.
• Liquibase requires Java. For Liquibase Java requirements, see Requirements. To check if you have Java installed, run java --version, or java -version on macOS`.

Download and extract Liquibase

1. Download the Liquibase CLI from https://www.liquibase.com/download.

2. Extract the Liquibase files. For example:

3. Open a command prompt to view the contents of your Liquibase installation:

Set your path variable

Add the Liquibase directory to your PATH so that you can run Liquibase commands from any location.

bashrc

profile

zsh

Verify your installation

Verify that the Liquibase installation was successful by running the following command:

Prepare a Neon database

For demonstration purposes, create a blog database in Neon with two tables, posts and authors.

1. Open the Neon Console.

2. Select your project.

3. Select Databases from the sidebar and create a database named blog. For instructions, see Create a database.

4. Using the Neon SQL Editor, add the following tables:

Retrieve your Neon database connection string

From the Neon Dashboard, retrieve your password and a Java connection string from the Connection Details widget. Use the selection drop-down menu.

Your Java connection string should look something like the one shown below.

Connect from Liquibase to your Neon database

1. Create a directory for your Liquibase project. For example:

2. Change to your project directory and create a liquibase.properties file.

3. Open the the liquibase.properties file in an editor and add entries for a liquibase changelog file and your database url. We'll call the changelog file dbchangelog.xml. You will use this file to define schema changes. For the url, specify the Neon connection string you retrieved previously.

Take a snapshot of your database

In this step, you will run the generateChangelog command in your project directory to create a changelog file with the current state of your database. We'll call this file mydatabase_changelog.xml.

You’ll get a changelog file for your database that looks something like this:

Create a schema change

Now, you can start making database schema changes by creating changesets and adding them to the database changelog file you defined in your liquibase.properties file. A changeset is the basic unit of change in Liquibase.

1. Create the changelog file where you will add your schema changes:

2. Add the following changeset, which adds a comments table to your database. Replace author="alex" id="myIDNumber1234" with your auther name and id, which you can retrieve from your changelog file, described in the previous step.

Deploy your change

Deploy your database schema change by running the update command:

Command output

If the command was successful, you’ll see output similar to the following:

Rollback a change

Try rolling back your last change by running the Liquibase rollbackCount command:

Command output

If the command was successful, you’ll see output similar to the following:

You can verify that creation of the comments table was rolled back viewing the blog database on the Tables page in the Neon console. Select Tables from the sidebar.

Next steps

Learn how to use Liquibase with Neon's database branching feature to set up a developer workflow. See Set up a developer workflow with Liquibase and Neon.

References

• Get started with Liquibase
• Setting up your Liquibase Workspace
• Liquibase Developer Workflow