Use different authentication for the reference database

Use different authentication for the reference database

The diff and diff-changelog commands open two connections, a target and a reference. Each platform authentication selector has a reference-scoped counterpart, so the two connections can authenticate differently: key-pair, OAuth, OIDC, or IAM on one side and a plain password on the other.

When you need this

Most comparisons run against two databases that sign in the same way, and need none of this. You need reference-scoped keys when the two sides authenticate differently, which usually means one of these:

• You are partway through an authentication migration. Production already uses key-pair, OAuth, OIDC, or IAM, and the database you compare against has not moved yet.

• Your reference database is a legacy or short-lived environment that still uses a username and password, such as a restored snapshot or a scratch instance.

• Your environments have different authentication policies, so a drift check between them necessarily crosses mechanisms.

Without reference-scoped keys, setting a platform’s authentication selector applies it to both connections, and the password side fails validation with a message saying the mechanism’s settings are required.

Each selector’s companion settings have reference-scoped counterparts too, following the same pattern: liquibase.snowflake.reference.privateKeyPath, liquibase.databricks.reference.oauth.clientId, liquibase.mongodb.reference.oidc.environment, liquibase.aws.reference.region, and so on.

How the reference connection decides

• Leave the reference keys unset and the reference connection inherits the target’s selector and companions. This is the previous behavior, so existing configurations keep working.

• Set a reference key and it overrides the inherited value for that connection only.

• Set the reference selector to DEFAULT and that connection falls back to password authentication, which is what makes a mixed run possible. The value is not case sensitive.

Liquibase validates each connection separately, and it validates the reference connection first. When the reference side is misconfigured, the error names the reference-scoped key rather than the target one, so you can tell which connection to fix.

Set these keys outside the command line

The reference-scoped keys are not accepted as command-line flags. Passing one returns Unexpected argument. Set them in your defaults file, as environment variables, or as Java system properties with -D. Environment variables follow the usual spelling, for example LIQUIBASE_AWS_REFERENCE_AUTH_TYPE.

If you already set authentication in the connection URL

You can also select a mechanism per connection inside the JDBC URL or connection string, such as authenticator= for Snowflake, AuthMech= for Databricks, or ?authMechanism= for MongoDB. That approach still works, and it is how mixed authentication was handled before these keys existed.

Prefer the reference-scoped keys. Selecting the mechanism in the URL bypasses the validation the extensions perform, so a misconfigured connection fails later and less clearly, and it splits your authentication settings across two places: part in the URL, part in your Liquibase configuration.

Example: key-pair on the target, password on the reference

In liquibase.properties:

• liquibase.snowflake.auth.type=PKI

• liquibase.snowflake.privateKeyPath=/path/to/rsa_key.p8

• liquibase.snowflake.reference.auth.type=DEFAULT

• referenceUsername=my_user

• referencePassword=my_password

Reverse the two selectors to authenticate the reference connection with the mechanism and the target with a password.

The opt-out works on companion settings too. Setting a companion such as liquibase.aws.reference.roleArn to DEFAULT means "do not inherit the primary value on this connection", so a reference connection can run plain IAM with no assume-role while the target uses one. Leaving a reference key empty still inherits the target’s value, so use DEFAULT when you want to suppress an inherited setting rather than replace it.