Using Liquibase with Cosmos DB

Azure Cosmos DB is a multi-model NoSQL database developed by Microsoft. For more information, see Azure Cosmos DB Documentation and Azure Cosmos DB: REST API Reference.

Supported versions

  • 4.33.0

Verification level

Compatible: Reported to work by the community. May have partially passed Foundational-level testing.

Note: A database's verification level indicates how well it works with different features in Liquibase and across different products, such as Liquibase Community and Liquibase Pro. For more information, see Liquibase Database Tutorials.

Prerequisites

Install drivers

To use Liquibase and Cosmos DB, you need two JAR files:

Place your JAR file(s) in the liquibase/lib directory. Read more: Adding and Updating Liquibase Drivers.

If you use Maven, you must include the driver JAR as a dependency in your pom.xml file. Read more: Configuring Liquibase Attributes in your Maven POM File.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.33.0</version>
</dependency>
<dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-cosmosdb</artifactId>
    <version>4.16.1</version>
</dependency>

Test your connection

  1. Ensure your Cosmos DB database is configured. See Quickstart: Build a Java app to manage Azure Cosmos DB SQL API data for more information.
  2. Specify the database URL in the Liquibase properties file. Liquibase does not parse the URL. You can either specify the full database connection string or specify the URL using your database's standard JDBC format:

  3. url: jdbc:cosmosdb://<host>:<accountKey>@<host>:<port>/<databaseName>?<Query Parameters>
    Type Example Notes
    Azure Cosmos DB Emulator
    jdbc:cosmosdb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:8080/testdb1
    This example shows the default account key. For more information, see Install and use the Azure Cosmos DB Emulator for local development and testing.
    Azure Cosmos DB
    jdbc:cosmosdb://AccountEndpoint=https://<cosmosdb-account-name>.documents.azure.com:443;
    AccountKey=<accountKey>;
    Replace <cosmosdb-cacount-name> with the name you chose for your Azure Cosmos DB. Replace <accountKey> with your private account key. For more information, see Tutorial: Connect to an Azure Cosmos account using an Azure Private Endpoint.

    Tip: To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file: liquibaseProLicenseKey: <paste code here>

  1. Create a text file called changelog (.xml, .sql, .json, or .yaml) in your project directory and add a changeset.
  2. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:
  3. liquibase --username=test --password=test --changelog-file=<changelog.xml> status

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

  4. Inspect the SQL with the update-sql command. Then make changes to your database with the update command.
  5. liquibase --changelog-file=<changelog.xml> update-sql
    liquibase --changelog-file=<changelog.xml> update
  6. From a database UI tool, ensure that your database contains the test_table you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

Related links