- Concept
- Version · 5.0.4
- User Guide
Use different authentication for the reference database
Last updated: August 21, 2026
The diff and diff-changelog commands open two connections, a target and a reference. Before Liquibase 5.0.4, every configuration setting resolved identically for both connections. Starting in Liquibase 5.0.4, settings that opt in can take a different value for the reference connection, so the two connections can authenticate differently.
How reference-scoped settings work
A setting that supports reference scoping reads its value from a sibling key named <namespace>.reference.<suffix> while the reference connection opens:
Leave the sibling key unset and the reference connection inherits the primary value. Existing configurations keep working unchanged.
Set the sibling key and the reference connection uses that value. The primary connection ignores it.
Set the sibling key to
DEFAULT(not case sensitive) and the setting resolves as if it were unset, falling back to the setting's default. Use this to suppress an inherited value rather than replace it.
The value resolves through the base setting, so its type conversion, default value, and secret masking still apply.
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 for liquibase.aws.reference.authType.
Which settings support reference scoping
Settings opt in individually, and in Liquibase 5.0.4 the core settings do not yet do so. The mechanism is used by database extensions that provide platform authentication selectors, so the target and reference connections can sign in differently, for example key-pair or IAM authentication on the target and a username and password on the reference. Each extension's documentation lists its reference-scoped keys.
For extension authors
Mark a configuration definition as reference-scopable with ConfigurationDefinition.Builder.referenceScoped(). While the reference connection opens, Liquibase resolves the definition from its <namespace>.reference.<suffix> sibling key, with the inherit, override, and DEFAULT behavior described above. Definitions that do not opt in behave exactly as before.