This feature is available in v8.8 and later.
Traditional packaging requires users to maintain a reference database, but this can be time consuming and cumbersome to manage. Using a PostgreSQL Ephemeral Database eliminates the need to manage an additional database on the pipeline. You simply configure Liquibase to create a temporary copy of a database in the pipeline to be used in place of the Reference Database. Once the copy is made, you will ensure that all of your changes work on the copy, implement them on your original database’s changelog, and then destroy the database copy. Follow this guide to learn how to implement this workflow.
How PostgreSQL copies are created
A PostgreSQL Ephemeral database copy is created using the following command
pg_dump -h <hostname> -p <port> -U <liquibase_user> -F c -n <schema(s)> -n <tracking_schema> --schema-only -f <backup_dir> <db_name> CREATE DATABASE <db_name>_eph pg_restore -h <hostname> -p <port> -U <liquibase_user> -F c -n <schema(s)> -n <tracking_schema> --schema-only -d <db_name>_eph <backup_dir>
Pre-requisites
Requires Liquibase Enterprise 8.8 and higher
The Liquibase user for the first database in the pipeline must have permission to create databases.
Usage
Using a PostgreSQL Ephemeral Database eliminates the need to manage an additional database on the pipeline. The ephemeral packaging feature creates a copy of the first database on the pipeline when the packager runs. All changes are performed on the copy and the copy is dropped when packaging is complete. If the final deploy is not skipped - it will deploy newly packaged changes on the first database on the pipeline.
It’s important to note that the database to be copied should always be the first database in the pipeline.
.png?version=1&modificationDate=1730489623608&cacheVersion=1&api=v2&width=574&height=244)
Backup and Restore Package Method
In order to implement an Ephemeral Database, the databaseBackupRestoreMethod package method on the deployPackager.properties needs to be configured.
A new package method called BackupRestoreEphemeralPostgres has been added.
Package Method Name | Description |
|---|---|
BackupRestoreEphemeralPostgres | The new database will be created on the same server as the original database. Eg. if I want to use the DEV database, the cloned db will be created on the same instance as the DEV database. |
See: Use the Required deployPackager.properties File
1. Update the deployPackager.properties
Update the deployPackager.properties file to set the following properties:
databaseBackupRestoreMethod=BackupRestoreEphemeralPostgres databaseBackupRestoreLocation=<location to house backup files>
2. Optional Step: Associated deployPackager.properties
These are packaging properties available specifically for the ephemeral database packaging method. They are optional if you would like to override the default values.
Property Name | Description |
|---|---|
ephemeralCopyName | [Optional] Defines a name for a DB copy (has impact on PostgreSQL Ephemeral copy only). Default name for the ephemeral copy will be source database name with Property Validation: Copy name should be up to 124 characters long, contain no spaces [ ], slashes [/] and semicolons [;] and cannot begin with a number. |
ephemeralCopyWithData | [Optional] By default Liquibase will copy databases without data. (*) If you would like to copy both the structure and data, use this boolean property. (*) There is one exception in that the data from the Property Validation: true/false |
ephemeralSkipFinalDeploy | [Optional] The default value for this setting is false. Any changes being packaged are deployed to the first database in the pipeline during the Deploy Packager operation. Setting this value to true allows changes to be packaged and changesets to be created and stored in the changelog.xml, but the deployment to the first database in the pipeline does not occur. Property Validation: true/false |
See: Use the Required deployPackager.properties File
3. Setup database permissions
Ensure the Liquibase user for the first database in the pipeline has the permission to create databases. This grant is eg. ALTER USER "USER_NAME" CREATEDB;
4. Remove existing REF dbDefs and references in the datical.project
In the datical.project file, remove any dbDef definitions for REF databases and also remove the references to these dbDefs in the plans/pipelines.