snapshot-reference

Last updated: January 21, 2026

The snapshot-reference command captures the current state of the reference-url database, which is the source database.

The snapshot-reference command has two modes:

When run without options, it gathers the current state of the database and shows a text-based version of the schema to STDOUT. When run with the --snapshot-format=json option, it creates a JSON file that represents the current state of the reference-url database. Alternatively, you can have a YAML-based output by using the --snapshot-format=yaml attribute.

Uses

The snapshot-reference command is typically used when you want to see changes in your sourcedatabase or keep a record of your current database state.

You can use the output of snapshot-reference with the diff and diff-changelog commands.

Note: It is best practice to use the --snapshot-format=json option for the diff and diff-changelog commands. Otherwise, you will get only a text report of your target database. This text report cannot be used for comparison in the future.

It can also be used to compare:

  • A previous database state to an online database.

  • A previous database state to another snapshot.

Note: Running a diff command by using at least one snapshot.json file is faster than using a diff command with two online databases. However, keep in mind that a snapshot will no longer reflect the current state of the database if the database is changed with the update command or if it is changed manually.

Syntax

To run the snapshot-reference command, specify your driver, classpath, and URL in the Liquibase properties file. You can also specify these properties in your command line.

Then run the snapshot-reference command:

liquibase snapshot-reference

To create a JSON file, add the --snapshot-format=json attribute:

liquibase --output-file=mySnapshot.json snapshot-reference --snapshot-format=json

Parameters

Note: The username and password attributes are not required for connections and systems which use alternate means of authentication. Also, you can specify database credentials as part of the url attribute.

Global parameters

Attribute

Definition

Requirement

--output-file=<string>

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Attribute

Definition

Requirement

--reference-url=<string>

The JDBC reference database connection URL

Required

--reference-default-catalog-name=<string>

The reference default catalog name to use for the database connection

Optional

--reference-default-schema-name=<string>

The reference default schema name to use for the database connection

Optional

--reference-driver=<string>

The JDBC driver class

Optional

--reference-driver-properties-file=<string>

The JDBC driver properties file

Optional

--reference-liquibase-catalog-name=<string>

Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+.

Optional

--reference-liquibase-schema-name=<string>

Reference database schema to use for Liquibase objects. Liquibase 4.24.0+.

Optional

--reference-password=<string>

The reference database password.

Optional

--reference-username=<string>

The reference database username.

Optional

--snapshot-filters=<string>

Liquibase Pro 4.26.0+. Controls which types of objects Liquibase includes in the snapshot. Can improve command performance. Specify multiple values in a comma-separated list. Accepted values are: catalog, checkConstraint, column, databasePackage, databasePackageBody, foreignKey, function, index, primaryKey, schema, sequence, storedProcedure, synonym, table, trigger, uniqueConstraint, and view. Default: all types.

Optional

--snapshot-format=<string>

Output format to use. Creates a file of the specified type that represents the current state of the database. Valid values: JSON, YAML, TXT. Default: TXT.

Optional

Note: The username and password attributes are not required for connections and systems which use alternate means of authentication. Also, you can specify database credentials as part of the url attribute.

Global parameters

Attribute

Definition

Requirement

globalArgs: { output-file: "<string>" }

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Attribute

Definition

Requirement

cmdArgs: { reference-url: "<string>" }

The JDBC reference database connection URL

Required

cmdArgs: { reference-default-catalog-name: "<string>" }

The reference default catalog name to use for the database connection

Optional

cmdArgs: { reference-default-schema-name: "<string>" }

The reference default schema name to use for the database connection

Optional

cmdArgs: { reference-driver: "<string>" }

The JDBC driver class

Optional

cmdArgs: { reference-driver-properties-file: "<string>" }

The JDBC driver properties file

Optional

cmdArgs: { reference-liquibase-catalog-name: "<string>" }

Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+.

Optional

cmdArgs: { reference-liquibase-schema-name: "<string>" }

Reference database schema to use for Liquibase objects. Liquibase 4.24.0+.

Optional

cmdArgs: { reference-password: "<string>" }

The reference database password.

Optional

cmdArgs: { reference-username: "<string>" }

The reference database username.

Optional

cmdArgs: { snapshot-filters: "<string>" }

Liquibase Pro 4.26.0+. Controls which types of objects Liquibase includes in the snapshot. Can improve command performance. Specify multiple values in a comma-separated list. Accepted values are: catalog, checkConstraint, column, databasePackage, databasePackageBody, foreignKey, function, index, primaryKey, schema, sequence, storedProcedure, synonym, table, trigger, uniqueConstraint, and view. Default: all types.

Optional

cmdArgs: { snapshot-format: "<string>" }

Output format to use. Creates a file of the specified type that represents the current state of the database. Valid values: JSON, YAML, TXT. Default: TXT.

Optional

Note: The username and password attributes are not required for connections and systems which use alternate means of authentication. Also, you can specify database credentials as part of the url attribute.

Global parameters

Attribute

Definition

Requirement

liquibase.outputFile: <string>

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Attribute

Definition

Requirement

liquibase.command.referenceUrl: <string>

liquibase.command.snapshotReference.referenceUrl: <string>

The JDBC reference database connection URL

Required

liquibase.command.referenceDefaultCatalogName: <string>

liquibase.command.snapshotReference.referenceDefaultCatalogName: <string>

The reference default catalog name to use for the database connection

Optional

liquibase.command.referenceDefaultSchemaName: <string>

liquibase.command.snapshotReference.referenceDefaultSchemaName: <string>

The reference default schema name to use for the database connection

Optional

liquibase.command.referenceDriver: <string>

liquibase.command.snapshotReference.referenceDriver: <string>

The JDBC driver class

Optional

liquibase.command.referenceDriverPropertiesFile: <string>

liquibase.command.snapshotReference.referenceDriverPropertiesFile: <string>

The JDBC driver properties file

Optional

liquibase.command.referenceLiquibaseCatalogName: <string>

liquibase.command.snapshotReference.referenceLiquibaseCatalogName: <string>

Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+.

Optional

liquibase.command.referenceLiquibaseSchemaName: <string>

liquibase.command.snapshotReference.referenceLiquibaseSchemaName: <string>

Reference database schema to use for Liquibase objects. Liquibase 4.24.0+.

Optional

liquibase.command.referencePassword: <string>

liquibase.command.snapshotReference.referencePassword: <string>

The reference database password.

Optional

liquibase.command.referenceUsername: <string>

liquibase.command.snapshotReference.referenceUsername: <string>

The reference database username.

Optional

liquibase.command.snapshotFilters: <string>

liquibase.command.snapshotReference.snapshotFilters: <string>

Liquibase Pro 4.26.0+. Controls which types of objects Liquibase includes in the snapshot. Can improve command performance. Specify multiple values in a comma-separated list. Accepted values are: catalog, checkConstraint, column, databasePackage, databasePackageBody, foreignKey, function, index, primaryKey, schema, sequence, storedProcedure, synonym, table, trigger, uniqueConstraint, and view. Default: all types.

Optional

liquibase.command.snapshotFormat: <string>

liquibase.command.snapshotReference.snapshotFormat: <string>

Output format to use. Creates a file of the specified type that represents the current state of the database. Valid values: JSON, YAML, TXT. Default: TXT.

Optional

Global parameters

Attribute

Definition

Requirement

JAVA_OPTS=-Dliquibase.outputFile=<string>

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Attribute

Definition

Requirement

JAVA_OPTS=-Dliquibase.command.referenceUrl=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referenceUrl=<string>

The JDBC reference database connection URL

Required

JAVA_OPTS=-Dliquibase.command.referenceDefaultCatalogName=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referenceDefaultCatalogName=<string>

The reference default catalog name to use for the database connection

Optional

JAVA_OPTS=-Dliquibase.command.referenceDefaultSchemaName=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referenceDefaultSchemaName=<string>

The reference default schema name to use for the database connection

Optional

JAVA_OPTS=-Dliquibase.command.referenceDriver=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referenceDriver=<string>

The JDBC driver class

Optional

JAVA_OPTS=-Dliquibase.command.referenceDriverPropertiesFile=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referenceDriverPropertiesFile=<string>

The JDBC driver properties file

Optional

JAVA_OPTS=-Dliquibase.command.referenceLiquibaseCatalogName=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referenceLiquibaseCatalogName=<string>

Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+.

Optional

JAVA_OPTS=-Dliquibase.command.referenceLiquibaseSchemaName=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referenceLiquibaseSchemaName=<string>

Reference database schema to use for Liquibase objects. Liquibase 4.24.0+.

Optional

JAVA_OPTS=-Dliquibase.command.referencePassword=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referencePassword=<string>

The reference database password.

Optional

JAVA_OPTS=-Dliquibase.command.referenceUsername=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.referenceUsername=<string>

The reference database username.

Optional

JAVA_OPTS=-Dliquibase.command.snapshotFilters=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.snapshotFilters=<string>

Liquibase Pro 4.26.0+. Controls which types of objects Liquibase includes in the snapshot. Can improve command performance. Specify multiple values in a comma-separated list. Accepted values are: catalog, checkConstraint, column, databasePackage, databasePackageBody, foreignKey, function, index, primaryKey, schema, sequence, storedProcedure, synonym, table, trigger, uniqueConstraint, and view. Default: all types.

Optional

JAVA_OPTS=-Dliquibase.command.snapshotFormat=<string>

JAVA_OPTS=-Dliquibase.command.snapshotReference.snapshotFormat=<string>

Output format to use. Creates a file of the specified type that represents the current state of the database. Valid values: JSON, YAML, TXT. Default: TXT.

Optional

Note: The username and password attributes are not required for connections and systems which use alternate means of authentication. Also, you can specify database credentials as part of the url attribute.

Global parameters

Attribute

Definition

Requirement

LIQUIBASE_OUTPUT_FILE=<string>

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Attribute

Definition

Requirement

LIQUIBASE_COMMAND_REFERENCE_URL=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_URL=<string>

The JDBC reference database connection URL

Required

LIQUIBASE_COMMAND_REFERENCE_DEFAULT_CATALOG_NAME=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_DEFAULT_CATALOG_NAME=<string>

The reference default catalog name to use for the database connection

Optional

LIQUIBASE_COMMAND_REFERENCE_DEFAULT_SCHEMA_NAME=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_DEFAULT_SCHEMA_NAME=<string>

The reference default schema name to use for the database connection

Optional

LIQUIBASE_COMMAND_REFERENCE_DRIVER=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_DRIVER=<string>

The JDBC driver class

Optional

LIQUIBASE_COMMAND_REFERENCE_DRIVER_PROPERTIES_FILE=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_DRIVER_PROPERTIES_FILE=<string>

The JDBC driver properties file

Optional

LIQUIBASE_COMMAND_REFERENCE_LIQUIBASE_CATALOG_NAME=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_LIQUIBASE_CATALOG_NAME=<string>

Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+.

Optional

LIQUIBASE_COMMAND_REFERENCE_LIQUIBASE_SCHEMA_NAME=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_LIQUIBASE_SCHEMA_NAME=<string>

Reference database schema to use for Liquibase objects. Liquibase 4.24.0+.

Optional

LIQUIBASE_COMMAND_REFERENCE_PASSWORD=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_PASSWORD=<string>

The reference database password.

Optional

LIQUIBASE_COMMAND_REFERENCE_USERNAME=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_REFERENCE_USERNAME=<string>

The reference database username.

Optional

LIQUIBASE_COMMAND_SNAPSHOT_FILTERS=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_SNAPSHOT_FILTERS=<string>

Liquibase Pro 4.26.0+. Controls which types of objects Liquibase includes in the snapshot. Can improve command performance. Specify multiple values in a comma-separated list. Accepted values are: catalog, checkConstraint, column, databasePackage, databasePackageBody, foreignKey, function, index, primaryKey, schema, sequence, storedProcedure, synonym, table, trigger, uniqueConstraint, and view. Default: all types.

Optional

LIQUIBASE_COMMAND_SNAPSHOT_FORMAT=<string>

LIQUIBASE_COMMAND_SNAPSHOT_REFERENCE_SNAPSHOT_FORMAT=<string>

Output format to use. Creates a file of the specified type that represents the current state of the database. Valid values: JSON, YAML, TXT. Default: TXT.

Optional

Liquibase Open Source snapshot-reference categories

  • Catalog

  • Column

  • Foreign Key

  • Index

  • Primary Key

  • Schema

  • Sequence

  • Unique Constraints

  • View

Liquibase Secure snapshot-reference categories

  • Package

  • Package Body

  • Procedures

  • Function

  • Trigger

  • Synonyms

  • Check Constraints

Output examples

The snapshot-reference command produces a JSON file that contains all your objects and places the file in the same directory as your changelog.

loading

The snapshot-reference command produces a JSON file that contains all your objects and places the file in the same directory as your changelog.

loading