snapshot

Last published July 28, 2025

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 targetdatabase 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. 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

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.

Parameters

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

--url=<string>

The JDBC database connection URL.

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.

Note: In the properties file and JAVA_OPTS only: in 4.18.0 and earlier, specify this parameter using the syntax defaultSchemaName. In 4.19.0 and later, use the syntax liquibase.command.defaultSchemaName.

Note: In Liquibase 4.12.0 and later, you can use mixed-case schema names if you set --preserve-schema-case to true. However, in Liquibase 4.12.0–4.22.0, the Liquibase validator still throws a DatabaseException error if you specify a mixed-case value of defaultSchemaName. In 4.23.0 and later, the Liquibase validator accepts any casing.

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 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>

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

--username=<string>

Username to connect to the target database.

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

Optional

Snapshot output examples

Liquibase Community 4.9.1 by Liquibase Output saved to C:\Users\Amber Williams\Documents\Maven_h2\mySnapshot.json Liquibase command 'snapshot' was executed successfully.