Getting Started Guide : How to install Liquibase and run operations against a MongoDB database running in Docker

So you want to learn how to use a database migration tool like Liquibase with a popular NoSQL database like MongoDB? Well, I can help with that!

In this how-to-guide, I will walk you through standing up your own MongoDB database that runs in a docker container, then show you how to use Liquibase to connect to it and finally execute Liquibase operations which will allow you to populate the database with collections and indexes on your MongoDB database.

Article Scope

1. Set up MongoDB running in docker
2. Install Liquibase 4.0 on local machine
3. Create a Liquibase Project
4. Run Liquibase update
5. Verify results on MongoDB

Setting the stage

The main purpose of this guide is to show you how easy it is to get started with Liquibase and why it’s a helpful tool for developers to employ when they need to manage their databases (even NoSQL ones like MongoDB!)

But before we get started, I’m going to explain what Liquibase is and how it works.

Liquibase is an open-source database schema change management solution which allows a user to manage revisions of database change scripts. Liquibase makes it easy for anyone involved in the application release process to:

• Track, version & deploy database changes
• Eliminate errors and delays when releasing databases

The root of all Liquibase changes is the changelog file. Liquibase uses a changelog to list all changes, in order, made to your database. It is a file that contains a record of all your database changes (called changesets). Liquibase uses this changelog record to execute any changes not yet applied to your database. We will use this Liquibase changelog concept to deploy changes to our MongoDB database in this tutorial.

OK, now let’s get started —

MONGODB

The first thing we need to do is to create a working MongoDB database environment to try out Liquibase with.

I love the ease and simplicity of Docker, so I’m going to run MongoDB locally on my machine in a docker container. I also like using compose files, so here’s what my docker-compose file looks like:

Note: I wanted to disable the default authentication when containing to the MongoDB database (since it is not necessary for the purposes of this tutorial), so I have chosen to not pass in MONGO_INITDB_ROOT_USERNAME & MONGO_INITDB_ROOT_PASSWORD as env vars.

We need to have a test database on the MongoDB instance to run liquibase scripts against AND I would also like this test database and test user(s) set up during the initialization of the docker container. I’m going to accomplish this by using an init script called `mongo-init.js` that contains the following:

What the above code bits will do is:

1. Run the latest version of MongoDB in a docker container
2. Create a database named “kristyldb”
3. Create a user named kristyl and assign the necessary database roles to this user.

Now start up your container by executing the following command from the same file system location as your docker-compose file:

docker-compose up -d

You can now verify that MongoDB is running as it should and that you can connect to it as your newly created user. There are a couple of ways you can do this —

• You can use the mongo shell provided by MongoDB. (I’m on MacOS and I provided the Homebrew link because it’s my preferred package manager).
• Or you can use the GUI provided via Robo 3T which I prefer for its visual benefits.

In the Robo 3T GUI, click to add a new connection and enter in your connection parameters such that it matches the values of the MongoDB database you created above.

LIQUIBASE

Now we know we have a working connection to our test database in MongoDB, so we can move on to setting up Liquibase to work with it.

INSTALLATION

First we need to get Liquibase installed locally.

1. Download and install Liquibase version 4.0.0.
2. Make sure you have set Liquibase in your PATH
3. Download the MongoDB JDBC jar file
4. Download the Liquibase MongoDB extension jar file
5. Place these two jar files in the liquibase/lib install directory

LIQUIBASE PROJECT

Now we need to create a Liquibase Project along with the associated files. And good news — you only need 2 files to get started with your first Liquibase Project!

1. A liquibase.properties file
2. A database changelog file

Here’s what you need to do:

1. In your directory of choice, create a new folder for your project give it a name. I’ve called mine “Liquibase_MongoDB”.
2. In your Liquibase_MongoDB folder, create a new text file and name it liquibase.properties.
3. Edit the liquibase.properties file to add the following properties:

The values above should correspond to the connection properties you specified when you set up the MongoDB database in step #1.

1. In your Liquibase_MongoDB folder, create a new xml file and name it mongodb.project.changelog1.xml.
2. Open the mongodb.project.changelog1.xml file and update the changelog file with the following:

The changelog above consists of just 1 changeset. This changeset is going to create a Collection named kristyl_Collection on your test database called kristyldb.

LIQUIBASE UPDATE

Now we have all the pieces in place to execute Liquibase operations against MongoDB.

1. Open up a terminal session.
2. Make sure you are in the “Liquibase_MongoDB” folder location.
3. Start with a Liquibase status operation just to make sure that everything is set up correctly.
4. Run `liquibase status`.

You should see a success message that looks like:

Liquibase command ‘status’ was executed successfully.

1. Now run `liquibase update`.
2. You’ll receive a success message when the update executes successfully.

Liquibase Community 4.0.0 by Datical
Starting Liquibase at 16:32:13 (version 4.0.0 #19 built at 2020–07–13 19:45+0000)
Liquibase: Update has been successful.

VERIFICATION

• Congratulations! You’ve created a collection named “kristyl_Collection” on your test database, kristyldb. Use Robo 3T to confirm that the objects exist in your database.

In addition, you can also see that 2 more collections have been created:

• DATABASECHANGELOG tracking collection — This collection 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 collection and only the new changesets that were not found in the DATABASECHANGELOG will be deployed. You will notice that a new data set was created in that table with the changeset information we have just deployed.
• DATABASECHANGELOGLOCK — This collection is used internally by Liquibase to manage access to the changelog collection during deployment.

CREATING INDEXES USING LIQUIBASE

“If you want to try deploying additional objects, try indexes. Here’s an example:

1. Open your mongodb.project.changelog1.xml file and update the existing changelog file to add another changeset that looks like this:

The additional changeset above will create 2 new collections along with an index on each of them.

1. Now run `liquibase update`
2. You should a success message from Liquibase again indicating that the deployment was successful.
3. And again you can go to Robo 3T and verify that your new objects exist on your collections

CLEANUP

When you are finished it is good practice to stop your MongoDB docker container, which you can do by running the command below.

docker-compose down --volumes

You can choose not to pass the--volumesflag — this is optional and will remove the data when you stop the container.

****************************************************************

And there you have it — you now have a Liquibase Project that is wired to deploy database objects via Liquibase xml changesets to your MongoDB database. From here on out, it is easy to continue to build out your database changes by adding more changesets to your master changelog.xml file.