Install the following tools before you begin. You will need the AWS CLI to manage credentials, the Session Manager Plugin to open the network tunnel in Step 5, and mongosh to verify your connection.

Liquibase uses the MongoDB driver's default AWS credential chain to resolve your base credentials, checking environment variables, the shared credentials/config file, web identity token (IRSA), container credentials, and the EC2 instance profile, in that order. Choose the method that matches your environment below.

Liquibase never logs AWS credential values, tokens, or SigV4 signatures, even at debug level. Connection strings are redacted before being written to logs.

Note: If Liquibase needs to assume a different IAM role to access the cluster, complete this step first, then see Step 3 (Assume a different IAM role).

Verify your credentials are working:

If Liquibase runs under one IAM identity but needs to assume a different role to access the cluster, configure AssumeRole.

Note: If you don't need to assume a different role, skip this step.

AssumeRole builds on the base credentials from Step 2. It does not provide credentials on its own. Complete Step 2 (Instance role or Environment variables) first, then add the following to your liquibase.properties file:

liquibase.mongodb.aws.region=your_aws_region
liquibase.mongodb.aws.roleArn=your_role_arn
liquibase.mongodb.aws.sessionName=your_session_name

Be sure to:

• Replace your_aws_region with the AWS region of your cluster. Required when using AssumeRole. For example, us-east-1

• Replace your_role_arn with the ARN of the role to assume. For example, arn:aws:iam::123456789012:role/your_role_name

• Replace your_session_name with a name to identify the session. Optional. If omitted, Liquibase generates one automatically. For example, liquibase-session

Note: liquibase.mongodb.aws.* properties can only be set in your liquibase.properties file, environment variables, or a defaults file. They are not accepted as -D command-line arguments.

Some changesets need to run raw mongosh commands or scripts that can't be expressed as a standard MongoDB change type. Liquibase supports this using the mongosh native executor (runWith="mongosh"). For details on configuring native executors, see Use native executors with MongoDB Secure.

Note: If you don't run changesets with runWith="mongosh", you can skip this step.

When a changeset runs through the mongosh executor, Liquibase automatically passes your resolved AWS credentials to the mongosh subprocess as environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN when present). If you configured AssumeRole in Step 3, the temporary credentials from the assumed role are passed instead of your base credentials. No additional configuration is needed.

Important: Open a dedicated terminal window for this step. The tunnel must stay running in its own terminal for the rest of the procedure. Do not use this terminal for anything else.

Use this step when running Liquibase on a local machine outside the DocumentDB cluster's VPC. If Liquibase runs on EC2, ECS, or another compute resource inside the same VPC as your cluster, skip this step.

aws ssm start-session opens an encrypted tunnel from your local machine to the DocumentDB cluster through a bastion instance in the VPC. Once the tunnel is running, Liquibase connects to localhost:27017, which forwards traffic to your cluster. For more information, see the AWS Systems Manager Session Manager documentation.

Be sure to:

• Replace your_instance_id with your bastion instance ID. For example, i-0123456789abcdef0

• Replace your_cluster_endpoint with your DocumentDB cluster endpoint. For example, mydb.cluster-abc123.us-east-1.docdb.amazonaws.com

• Replace your_aws_region with your AWS region. For example, us-east-1

Note: If a local MongoDB instance is already using port 27017, change localPortNumber to an available port (for example, 27020), and update the port in your connection string in Step 8 to match.

Leave this terminal running. Open a new terminal window and complete the remaining steps there.

DocumentDB requires TLS for all connections and uses AWS's own private Certificate Authority (CA), which is not trusted by default on most systems. The global certificate bundle contains the CA certificates your client needs to verify it is connecting to a legitimate DocumentDB cluster. Without it, the TLS handshake fails.

Download the bundle and store global-bundle.pem in a location accessible to Liquibase. You will reference this path in Step 8.

Java does not read tlsCAFile from the connection string. Instead, it uses its own certificate trust store. Run the script below to create a JKS trust store from global-bundle.pem using keytool, then set JAVA_TOOL_OPTIONS to point Liquibase to it.

Set the url property in your liquibase.properties file. If you do not already have one, create it in the directory where you will run Liquibase.

Note: authSource=$external is required for MONGODB-AWS authentication. The Liquibase MongoDB extension sets this automatically. You do not need to include it in the connection string.

Run the liquibase status command against your cluster. For example:

Be sure to:

• Replace your_changelog_dir with the directory containing your changelog file. For example, C:\Users\your_username\my-project

• Replace your_changelog_file with the name of your changelog file. For example, changelog.xml