Using Liquibase with MongoDB

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

Prerequisites

Before using Liquibase with your database, ensure you have:

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 MongoDB on your machine, begin with the following steps:

  1. In your project folder, create a new text file and name it dbchangelog.xml. Add 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"
	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-4.9.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-4.9.xsd">
</databaseChangeLog>
  1. Add the following properties to the Liquibase properties file:
  2. changelog-file: dbchangelog.xml
    url: mongodb://hostname:27017/myDatabase
    username: username
    password: password

Note: If you are unsure about how to configure the url property, refer to Connection String URI Format. Although you can store authentication information in the Liquibase properties file, we recommended storing user credentials in a secure repository or entering them from the CLI when running a command.

  1. Add a changeset to the changelogchangesets are uniquely identified by author and id attributes. Liquibase attempts to execute each changeset in a transaction that is committed at the end. In the dbchangelog.xml file, add a new collection myCollection changesets as follows:
  2. <?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-4.9.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-4.9.xsd">
    
    <changeSet id="1" author="bob">
    	<ext:createCollection collectionName="myCollection">
    		<ext:options>
    		{
    		validator: {
    			$jsonSchema: {
    				bsonType: "object",
    				required: ["name", "address"],
    				properties: {
    					name: {
    					bsonType: "string",
    					description: "The Name"
    					},
    			address: {
    				bsonType: "string",
    				description: "The Address"
    						}
    					}
    				}
    			},
    			validationAction: "warn",
    			validationLevel: "strict"
    			}
    			</ext:options>
    		</ext:createCollection>
    	</changeSet>
    </databaseChangeLog>
  1. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful. You can pass arguments in the CLI or keep them in the Liquibase properties file.
  2. liquibase --username=test --password=test --changelog-file=<changelog.xml> status
  3. Run your first update with the update command, which makes changes to your database. You can also run the update-sql command to inspect the SQL before running the update command.
  4. liquibase --changelog-file=<changelog.xml> update-sql
    liquibase --changelog-file=<changelog.xml> update

From a database UI tool, ensure that your database contains the table you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

Tip: You can use MongoDB Compass to easily view collections in your database. For example, run the commands use myDatabase and db.myCollection.find().

See Also