snapshot-reference

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 source database 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. 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-reference command:

liquibase snapshot-reference

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

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

Global arguments

Tip: For best results, specify all commands and parameters in the --kebab-case format in the CLI. If your preference is camelCase, it also works in the CLI.

Attribute	Definition	Requirement
--output-file	File path to where the command output will be written. If not specified, output goes to STDOUT	Optional

Command arguments

Attribute	Definition	Requirement
--reference-url	The JDBC reference database connection URL	Required
--driver	The JDBC driver class	Optional
--driver-properties-file	The JDBC driver properties file	Optional
--reference-default-catalog-name	The reference default catalog name to use for the database connection	Optional
--reference-default-schema-name	The reference default schema name to use for the database connection	Optional
--reference-password	The reference database password. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.	Optional
--reference-username	The reference database username. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.	Optional
--snapshot-format	Creates a JSON or YAML file that represents the current state of the database.	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-reference 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 source database matches the changelog file.
3. Take a snapshot of the local development database by running the snapshot-reference command:

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

4. Manually change the local development database if needed.
5. Append changes to the changelog by running the diff-changelog command:

liquibase diff-changelog --reference-url=jdbc:oracle:thin://localhost:9090/mem:test --url=offline:mysql?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:mysql?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>".

6. Review the changelog file to ensure that it matches your expectations of the manual changes that were made.
7. Mark the manual changes as deployed in the local development database by running the changelog-sync command:

liquibase changelog-sync

8. Commit the changes to the source control.

Liquibase Open Source 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

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