EDITION: ENTERPRISE

A snapshot is a representation of the database schema at a moment in time that is stored in a single binary file.  The snapshot can be taken from a database, a schema-model folder, or an empty source. The snapshot file is a binary file containing information about the structure of a database; it does not contain any table data.

Snapshots can be used in a variety of Flyway workflows, such as drift analysis and rollbacks.

See the Snapshot reference for further details.

Snapshot history table

Capturing and embedding snapshots on deployment

Snapshots can be embedded in a target database on deployment success (using migrate.saveSnapshot, undo.saveSnapshot, or deploy.saveSnapshot) or by invoking the snapshot command and specifying the snapshot history table as a location.

Storing snapshots in the target database is the recommended way of doing drift analysis. It requires less effort to set up than the alternatives (using a build environment or saving a snapshot to a file which is persisted somewhere accessible between deployment runs) and there is less chance of configuration error. It also means a drift check can be performed easily at any time, whether as part of a deployment or not.

Embedded snapshots also provide a potential means of doing rollbacks, as you can generate a migration or deployment script to revert from the current database state to the state of a past snapshot.

Location

Snapshots can be saved to disk or embedded in the target database in a Flyway-managed table.  By default this table is named flyway_snapshot_history and will be located in your default schema.  For the saveSnapshot parameter on the deploy, migrate, and undo commands, the snapshot will be stored in the flyway_snapshot_history table by default.

The name of Flyway's snapshot history table can be customized using snapshot.historyTable.

The schema in which to create the table can be configured using defaultSchema.  If a defaultSchema is not specified, then the first schema defined in the list of schemas is used. If no schemas are specified, then it will be located in your database's default schema.

The tablespace in which to create the table can be configured using tablespace.

History limit

Snapshots are compressed before insertion into the table.  By default, the snapshot.historyLimit setting is set to 1, so only a single record is ever stored in the table.  Running a new snapshot command will overwrite this entry.

You can customize the snapshot.historyLimit to store more snapshots.  Expanding the number of entries gives a wider recent history window, allowing for comparison between or rollback to different database schema states, though more entries will consume a little more space in the database.

Name column

Snapshots can be given a name as part of the snapshot.filename location configuration.

If there are multiple entries in the table and the name is unique, it can be used as a basis for looking a snapshot entry up.

The name can be null. If the snapshot is generated using migrate.saveSnapshot, undo.saveSnapshot, or deploy.saveSnapshot, the name with default to a non-unique description e.g. "Snapshot following deployment" or "Snapshot following migrate". 

Version column

If the snapshot source is a database, then the version column will be populated with the greatest applied migration version in the database (if any). If the source is migrations, it will be the build version if set, or else the highest migration in your configured locations. For schema model or empty sources the version column will be null.

This column is currently purely informational.