snapshot

The snapshot command captures the current state of the url database, which is the target database.

The snapshot 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 url database. Alternatively, you can have a YAML-based output by using the --snapshot-format=yaml attribute.

Uses

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

You can use the output of snapshot 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.

In Liquibase Pro 4.26.0 and later, you can use the --snapshot-filters parameter to limit the types of database objects you include in your snapshot. If your database is very large, including only the objects relevant to you in the snapshot can improve the command's performance.

Syntax

To run the snapshot command, specify your driver, classpath, and URL in the Liquibase properties file. For more information, see Create and Configure a liquibase.properties File. You can also specify these properties in your command line.

Then run the snapshot command:

liquibase snapshot

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

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

To only include data types you specify, add the --snapshot-filters parameter:

liquibase snapshot --snapshot-filters=catalog,index,schema,table

Parameters

Global arguments

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 arguments

Attribute Definition Requirement

--url=<string>

The JDBC database connection URL. See Using JDBC URL in Liquibase.

Required

--default-catalog-name=<string>

Name of the default catalog to use for the database connection

Optional

--default-schema-name=<string>

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

Optional

--driver=<string>

The JDBC driver class

Optional

--driver-properties-file=<string>

The JDBC driver properties file

Optional

--password=<string>

Password to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

--schemas=<string>

Specifies schemas to be able to compare a multi-schema database to its snapshot

Optional

--snapshot-filters=<string>

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. Liquibase Pro 4.26.0+. 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.

Optional

--username=<string>

Username to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

Global arguments

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 arguments

Attribute Definition Requirement

cmdArgs: { url: "<string>" }

The JDBC database connection URL. See Using JDBC URL in Liquibase.

Required

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

Name of the default catalog to use for the database connection

Optional

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

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

Optional

cmdArgs: { driver: "<string>" }

The JDBC driver class

Optional

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

The JDBC driver properties file

Optional

cmdArgs: { password: "<string>" }

Password to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

cmdArgs: { schemas: "<string>" }

Specifies schemas to be able to compare a multi-schema database to its snapshot

Optional

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

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. Liquibase Pro 4.26.0+. 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.

Optional

cmdArgs: { username: "<string>" }

Username to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

Global arguments

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 arguments

Attribute Definition Requirement

liquibase.command.url: <string>

liquibase.command.<cmdName>.url: <string>

The JDBC database connection URL. See Using JDBC URL in Liquibase.

Required

liquibase.command.defaultCatalogName: <string>

liquibase.command.<cmdName>.defaultCatalogName: <string>

Name of the default catalog to use for the database connection

Optional

liquibase.command.defaultSchemaName: <string>

liquibase.command.<cmdName>.defaultSchemaName: <string>

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

Optional

liquibase.command.driver: <string>

liquibase.command.<cmdName>.driver: <string>

The JDBC driver class

Optional

liquibase.command.driverPropertiesFile: <string>

liquibase.command.<cmdName>.driverPropertiesFile: <string>

The JDBC driver properties file

Optional

liquibase.command.password: <string>

liquibase.command.<cmdName>.password: <string>

Password to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

liquibase.command.schemas: <string>

liquibase.command.<cmdName>.schemas: <string>

Specifies schemas to be able to compare a multi-schema database to its snapshot

Optional

liquibase.command.snapshotFilters: <string>

liquibase.command.<cmdName>.snapshotFilters: <string>

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. Liquibase Pro 4.26.0+. Default: all types.

Optional

liquibase.command.snapshotFormat: <string>

liquibase.command.<cmdName>.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.

Optional

liquibase.command.username: <string>

liquibase.command.<cmdName>.username: <string>

Username to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

Global arguments

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 arguments

Attribute Definition Requirement

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.url=<string>

The JDBC database connection URL. See Using JDBC URL in Liquibase.

Required

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.defaultCatalogName=<string>

Name of the default catalog to use for the database connection

Optional

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.defaultSchemaName=<string>

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

Optional

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.driver=<string>

The JDBC driver class

Optional

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.driverPropertiesFile=<string>

The JDBC driver properties file

Optional

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.password=<string>

Password to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.schemas=<string>

Specifies schemas to be able to compare a multi-schema database to its snapshot

Optional

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

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

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. Liquibase Pro 4.26.0+. Default: all types.

Optional

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.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.

Optional

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

JAVA_OPTS=-Dliquibase.command.<cmdName>.username=<string>

Username to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

Global arguments

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 arguments

Attribute Definition Requirement

LIQUIBASE_COMMAND_URL=<string>

LIQUIBASE_COMMAND_<CMDNAME>_URL=<string>

The JDBC database connection URL. See Using JDBC URL in Liquibase.

Required

LIQUIBASE_COMMAND_DEFAULT_CATALOG_NAME=<string>

LIQUIBASE_COMMAND_<CMDNAME>_DEFAULT_CATALOG_NAME=<string>

Name of the default catalog to use for the database connection

Optional

LIQUIBASE_COMMAND_DEFAULT_SCHEMA_NAME=<string>

LIQUIBASE_COMMAND_<CMDNAME>_DEFAULT_SCHEMA_NAME=<string>

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

Optional

LIQUIBASE_COMMAND_DRIVER=<string>

LIQUIBASE_COMMAND_<CMDNAME>_DRIVER=<string>

The JDBC driver class

Optional

LIQUIBASE_COMMAND_DRIVER_PROPERTIES_FILE=<string>

LIQUIBASE_COMMAND_<CMDNAME>_DRIVER_PROPERTIES_FILE=<string>

The JDBC driver properties file

Optional

LIQUIBASE_COMMAND_PASSWORD=<string>

LIQUIBASE_COMMAND_<CMDNAME>_PASSWORD=<string>

Password to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

LIQUIBASE_COMMAND_SCHEMAS=<string>

LIQUIBASE_COMMAND_<CMDNAME>_SCHEMAS=<string>

Specifies schemas to be able to compare a multi-schema database to its snapshot

Optional

LIQUIBASE_COMMAND_SNAPSHOT_FILTERS=<string>

LIQUIBASE_COMMAND_<CMDNAME>_SNAPSHOT_FILTERS=<string>

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. Liquibase Pro 4.26.0+. Default: all types.

Optional

LIQUIBASE_COMMAND_SNAPSHOT_FORMAT=<string>

LIQUIBASE_COMMAND_<CMDNAME>_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.

Optional

LIQUIBASE_COMMAND_USERNAME=<string>

LIQUIBASE_COMMAND_<CMDNAME>_USERNAME=<string>

Username to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

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.

Using snapshot in the diff-changelog commands

You can use the JSON format snapshot file in the diff and diff-changelog commands. One of the typical workflows is the following:

  1. Make sure your local environment is up-to-date by getting the latest changelog from source control.
  2. Configure the Liquibase properties file to point to a local development database and run the update command to ensure your target database matches the changelog file.
  3. Take a snapshot of the local development database by running the snapshot command:
  4. liquibase --output-file=myschemaSnapshot.json snapshot --snapshot-format=json
  5. Manually change the local development database if needed.
  6. Append changes to the changelog by running the diff-changelog command:
  7. liquibase diff-changelog --reference-url=jdbc:oracle:thin://localhost:9090/mem:test --url=offline:oracle:thin?snapshot=mySnapshot.json

    Note: If you want to see changes without appending them to the changelog file, add --changelog-file=mydiffchangelog.xml to the diff-changelog command:

    liquibase diff-changelog --reference-url=jdbc:oracle:thin://localhost:9090/mem:test --url=offline:oracle:thin?snapshot=mySnapshot.json --changelog-file=mydiffchangelog.xml

    Note: The format for the URL is the following: offline: <db_type>?snapshot=<path/to/snapshot.json>. Use the name of your database type from the list of the supported databases in place of <db_type> and the path relative to where the command is running in place of <path/to/snapshot.json>. If you are using another database, like H2, you may need to wrap your URL in ": "offline:<db_type>?snapshot=<path/to/snapshot.json>".

  8. Review the changelog file to ensure that it matches your expectations of the manual changes that were made.
  9. Mark the manual changes as deployed in the local development database by running the changelog-sync command:
  10. liquibase changelog-sync
  11. Commit the changes to the source control.

Liquibase Open Source snapshot categories:

  • Catalog
  • Column
  • Foreign Key
  • Index
  • Primary Key
  • Schema
  • Sequence
  • Unique Constraints
  • View

Liquibase Pro snapshot categories:

  • Package
  • Package Body
  • Procedures
  • Function
  • Trigger
  • Synonyms
  • Check Constraints

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

Related links