snapshot-reference
The snapshot-reference
command captures the current state of the referenceURL
database, which is the source 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
--snapshotFormat=JSON
option, it creates a JSON file that represents the current state of the referenceURL database. Alternatively, you can have a YAML-based output by using the--snapshotFormat=yaml
attribute.
Uses
The snapshot-reference
command is typically used when you want to see changes in your source database or keep a record of your current database state.
The snapshot can be used in the diff command or diff-changelog command.
Note: It is best practice to use the --snapshotFormat=JSON
option for the diff
and diff-changelog
commands. Otherwise, you will get only a text report of your source 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.
Running the snapshot-reference
command
To run the snapshot-reference
command, specify the driver, classpath, and URL in the Liquibase properties file. For more information, see Specifying Properties in a Connection Profile. You can also specify these properties in your command line.
Then run the snapshot-reference
command:
liquibase snapshot-reference
Note: To create a JSON file, add the --snapshotFormat=json
attribute while running the command:
liquibase --output-file=mySnapshot.json snapshot-reference --snapshotFormat=json
Note: Enter the name of the output file that you want to use in place of mySnapshot.json
. Additionally, include --snapshotFormat=json
to create a file in a JSON format.
snapshot-reference
global attributes
Attributes | Definition | Requirement |
---|---|---|
--username
|
The database username | Required |
--password
|
The database password | Required |
--url
|
The JDBC database connection | Required |
|
Specifies the file path to where the snapshot JSON or YAML will be written | Optional |
* If not specified, a JSON or YAML output goes to STDOUT.
Note: The username
and password
attributes are not required for connections and systems which use alternate means of authentication.
snapshot-reference
command attributes
Attributes | Definition | Requirement |
---|---|---|
--snapshotFormat
|
Creates a JSON or YAML file that represents the current state of the database. | Optional |
Using the snapshot
in the diff
and 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:
- Make sure your local environment is up-to-date by getting the latest changelog from source control.
- 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. -
Take a snapshot of the local development database by running the
snapshot-reference
command:
liquibase --output-file=mySnapshot.json snapshot-reference --snapshotFormat=json
- Manually change the local development database if needed.
- Append changes to the changelog by running the
diff-changelog
command:
liquibase --url=jdbc:oracle:thin://localhost:9090/mem:test --referenceUrl=offline:mysql?snapshot=mySnapshot.json diff-changelog
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 --url=jdbc:oracle:thin://localhost:9090/mem:test --referenceUrl=offline:mysql?snapshot=mySnapshot.json --changelog-file=mydiffchangelog.xml diff-changelog
Note: The format for the referenceUrl 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>
: "offline:<db_type>?snapshot=<path/to/snapshot.json>"
.
- Review the changelog file to ensure that it matches your expectations of the manual changes that were made.
- Mark the manual changes as deployed in the local development database by running the changelog-sync command:
liquibase changelog-sync
- Commit the changes to the source control.

When running the snapshot-reference
command with the --snapshotFormat
attribute, the output can be as follows:
Liquibase Community 4.9.1 by Liquibase
Output saved to C:\Users\Amber Williams\Documents\Maven_h2\mySnapshot.json
Liquibase command 'snapshot-reference' was executed successfully.
When running the snapshot-reference
command without indicating the --snapshotFormat
, you receive the following output:
Liquibase Community 4.9.1 by Liquibase
Database snapshot for jdbc:h2:tcp://localhost:9090/mem:integration
-----------------------------------------------------------------
Database type: H2
Database version: 2.1.210 (2022-01-17)
Database user: DBUSER
Included types:
liquibase.structure.core.Catalog
liquibase.structure.core.Column
liquibase.structure.core.ForeignKey
liquibase.structure.core.Index
liquibase.structure.core.PrimaryKey
liquibase.structure.core.Schema
liquibase.structure.core.Sequence
liquibase.structure.core.Table
liquibase.structure.core.UniqueConstraint
liquibase.structure.core.View
Liquibase command 'snapshot-reference' was executed successfully.
The snapshot-reference
command produces a JSON file that contains all your objects and places the file in the same directory as your changelog.

Database snapshot for jdbc:h2:tcp://localhost:9090/mem:integration
-----------------------------------------------------------------
Database type: H2
Database version: 2.1.210 (2022-01-17)
Database user: DBUSER
Included types:
liquibase.structure.core.Catalog
liquibase.structure.core.Column
liquibase.structure.core.ForeignKey
liquibase.structure.core.Index
liquibase.structure.core.PrimaryKey
liquibase.structure.core.Schema
liquibase.structure.core.Sequence
liquibase.structure.core.Table
liquibase.structure.core.UniqueConstraint
liquibase.structure.core.View
Liquibase Community snapshot-reference
categories:
- Catalog
- Column
- Foreign Key
- Index
- Primary Key
- Schema
- Sequence
- Unique Constraints
- View
Liquibase Pro snapshot-reference
categories:
- Package
- Package Body
- Procedures
- Function
- Trigger
- Synonyms
- Check Constraints