snapshotReference command

The snapshotReference 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.


The snapshotReference 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 diffChangeLog command.

Note: It is best practice to use the --snapshotFormat=JSON option for the diff and diffChangeLog 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 snapshotReference command

To run the snapshotReference command, you need to specify your driver, class path, URL, and user authentication information in your file. For more information, see Creating and configuring a file. You can also specify these properties in your command line.

Then run the snapshotReference command:

liquibase snapshotReference

Note: To create a JSON file, add the --snapshotFormat=json attribute while running the command:

liquibase --outputFile=myschemaSnapshot.json snapshotReference --snapshotFormat=json

Note: Enter the name of the output file that you want to use in place of myschemaSnapshot.json. Additionally, include --snapshotFormat=json to create a file in a JSON format.

snapshotReference global attributes

Attributes Definition Requirement
--changeLogFile The root changelog Required
--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.

snapshotReference command attributes

Attribute 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 diffChangeLog commands

You can use the JSON format snapshot file in the diff and diffChangeLog 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 your file to point to a local development database and run the update command to ensure it has the latest schema.
  3. Take a snapshot of the local development database by running the snapshotReference command:
liquibase --outputFile=myschemaSnapshot.json snapshotReference --snapshotFormat=json
  1. Manually change the local development database if needed.
  2. Append changes to the changelog by running the diffChangeLog command:
liquibase --url=jdbc:oracle:thin://localhost:9090/mem:test --referenceUrl=offline:mysql?snapshot=myschemaSnapshot.json diffChangeLog

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

liquibase --url=jdbc:oracle:thin://localhost:9090/mem:test --referenceUrl=offline:mysql?snapshot=myschemaSnapshot.json --changeLogFile=mydiffchangelog.xml diffChangeLog

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

  1. Review the changelog to ensure that it matches your expectations of the manual changes made.
  2. Mark the manual changes as deployed in the local development database by running the changelogSync command:
liquibase changeLogSync
  1. Commit the changes to the source control.

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

Liquibase Community snapshotReference categories:

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

Liquibase Pro snapshotReference categories:

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