Liquibase Enterprise was formerly known as Datical DB.
Use the Required deployPackager.properties File
deployPackager.properties
file when a new project is created. This works in the CLI, GUI, or a project_creator groovy script.A project must have a deployPackager.properties file in order for SQL scripts to be packaged for it.
deployPackager.properties Configuration
Before using the Deployment Packager, a deployPackager.properties will need to be created in the top level of your Datical project directory. This property file contains a variety of configuration information used by the Deployment Packager to interact with SCM solutions and to perform database backups and restorations.
Note: there is a sample deployPackager.properties file provided in DaticalDB/repl/scripts.
Properties Prefixes for SQL Code and Datical Project Files
The property prefix indicates the type of files it affects and the location of those files.
- sqlScm prefix - SQL code files (in predetermined subdirectories)
- ddbScm prefix - Datical project files (in a predetermined hierarchy)
When properties for the project are not specified (ddbScm prefix), the values typically default to the properties for the SQL code (sqlScm prefix)
Pipeline and DbDef Branch Settings
In order for the Deployment Packager to process the appropriate scripts for a specific dbdef or pipeline, the SCM branch name and the ID for the last import processed need to be tracked separately in the deployPackager.properties files. These properties should take the following form:
- Branch name:
- {PipelineName}.sqlScmBranch
- {DbDefName}.sqlScmBranch for the branch name
- Last
- {PipelineName}.sqlScmLastImportID
- {DbDefName}.sqlScmLastImportID.
Refer to the properties in the bottom section of the file below for an example of the Deployment Pipeline specific properties.
Property List for deployPackager.properties
The following properties can be set in the deployPackager.properties
file: (note that these properties are NOT in alphabetical order)
Name | Applies to | Description |
---|---|---|
databaseBackupRestoreLocation | Backup | Location to use for packager-driven backups of the database. During processing, Deployment Packager makes backups of the database that are normally stored on the database server itself. Depending on your DBMS, the location may need to be specified as directory or a specific file.
|
db2BackupDir.<referenceDBName>=0 | Backup | DB2 Only: Set automatically after the first execution of Deployment Packager. The warning from the first execution of packager on a given database can be ignored. |
ddlExcludeList | Compares | SQL code types to exclude from a compare, typically to improve performance. When packaging DDL scripts, Deployment Packager compares the before and after state of the reference database. Use this property to exclude object types from the comparison. Values can be:
Example ddlExcludeList property setting ddlExcludeList="package,packagebody,procedure,function,trigger,view" ddlExcludeList=package,packagebody,procedure,function,trigger,view |
ddbScmBranch | Project files | The SCM branch to use. If not specified, Deployment Packager uses the value from sqlScmBranch. |
ddbScmDoCheckout | Project files | If this is not present or is set to
|
ddbScmLastImportID | Project files | The SCM system ID for the most recently processed SQL code check in. It is automatically updated when the Deployment Packager completes successfully. Note: Do not leave blank. Do not use the most recent check-in. For first time use, use an ID from an earlier check-in.
|
ddbScmPath | Project files | Path to the local copy of the SCM repository. If this is not present, Deployment Packager will use the value from sqlScmPath. |
ddbScmSystem | Project files | SCM type – one of git May be different than the sqlScmSystem. If not specified, Deployment Packager uses the value from sqlScmSystem. |
enableBackupRestore | Backup | When the Packager is run in 'dbdef=' mode, the backup and restore routines can be skipped for certain sensitive environments. The value of this property is a comma separated list of the environments in which the Packager should perform backup and restore tasks. NOTE: Backup and restore tasks are NOT recommended for environments beyond development & test. |
oracleBackupNoCrossSchemaFk | When set to true Cross Schema Foreign Keys will not be included in the backup and older backups containing Foreign Keys will not apply those items during a restore. The backup/restore method will not be affected by this property if this property is absent in the deployPackager.properties file or if the value is false. | |
oracleBackupNoGrants | When set to true Grants will not be included in the backup and older backups containing Grants will not apply those items during a restore. The backup/restore method will not be affected by this property if this property is absent in the deployPackager.properties file or if the value is false. | |
oracleBackupNoDropSchema | When set to true, the Schema(s) will not be dropped. Instead all objects (such as tables, constraints, views, materialized views, functions, procedures, sequences, packages, triggers, synonyms, and user types) within the Schema(s) will be dropped instead. The backup/restore method will not be affected by this property if this property is absent in the deployPackager.properties file or if the value is false. | |
scmBranchHandling | SCM | Specifies how to handle branches in a multiple-branch project, one of two methods:
See "Pipeline and DbDef Branch Settings" below. |
sqlScmBranch | SQL code files | The repository branch to be used for SQL code. Format varies by SCM:
|
sqlScmDoCheckout | SQL code files | If this is not present or is set to
|
sqlScmLastImportID | SQL code files | The SCM system ID for the most recently processed SQL code check in. It is automatically updated when the Deployment Packager completes successfully. Note: Do not leave blank. Do not use the most recent check-in. For first time use, use an ID from an earlier check-in.
|
sqlScmPath | SQL code files | Path to the directory for SQL code in the local copy of the SCM repository. Can be an absolute path or path relative to the project directory. When packager determines the location of SQL code, it builds the location from sqlSCMPath and sqlScmSQLBaseDir. On Windows, backslashes must be doubled. Example: sqlScmPath=c:\\users\\username\\scmworkdir\\projectname |
sqlScmSQLBaseDir | SQL code files | Top level directory for SQL code stored in the local copy of the repository. This is a name only, not a path. If set to '.' uses the value of sqlScmPath. This directory contains:
If not specified, a default directory name When packager determines the location of SQL code, it builds the location from sqlSCMPath and sqlScmSQLBaseDir. |
sqlScmSystem | SQL code files | SCM type – one of git |
commitMsgLabelRegexp | SQL code files | By default, the Deploy Packager will scan the commit messages in your SQL code repo for values in square brackets. These values will be added as labels to the change sets that are produced by the files in that commit. For example: Commit Message: Adding column to hold area code information for [JIRA-1234] Change Set Label: JIRA-1234
commitMsgLabelRegexp=JIRA (\\d{6}) Commit Message: Adding column to hold area code information for JIRA 4321 which requires phone number separation Change Set Label: 4321 NOTE: If you provide a different pattern for matching desired label values, the values in square brackets will no longer be included as labels on change sets. |
databaseBackupRestoreMethod | Backup | Class name to use for custom backup and restore. The class is implemented in a .groovy script.
|
extensionsPath | Backup | Path to directory containing .groovy files that implement a custom backup and restore method. If not specified, the following directory is used: <datical-install>/repl/scripts/extensions . |
databaseBackupMode | Backup | Specifies how to manage reference database backups that are required for deployments.
|
oracleBackupErrorWhitelist | Backup (Oracle Only) | A comma separated list of Oracle error codes to be ignored when evaluating expdp import/restore output for errors. (This property is only available with versions 7.18 and higher.) During an Oracle backup that uses local expdp / impdp clients OR the DATAPUMP API on the server, error messages are compared to the white-list:
Example: oracleBackupErrorWhitelist=ORA-39173,ORA-39181 |
oracleRestoreErrorWhitelist | Restore (Oracle Only) | A comma separated list of Oracle error codes to be ignored when evaluating
Example: oracleRestoreErrorWhitelist=ORA-31684,ORA-39111,ORA-39151 |
parallel | Backup | Oracle only. Maximum of parallel threads for expdp and impdp to use during backup and restore. |
archive | Processing | Archive SQL scripts in the archive directory after processing. This is done for SQL code in the ddl, sql_direct, data_dml directories. Archiving is done by default. Set to false to override the default behavior. If not set or if set to true, archiving is done as usual. The archive property has been deprecated. Instead it is preferable to set the newer rerunnable property in the metadata.properties of each relevant folder. |
validateRollback | SQL code files | Test the rollback script provided for a SQL script (-rollback), unless set to none. The rollback script must be able to restore the database to its state before the SQL script was run. During testing, packager runs a test rollback and a test deploy from the rolled-back state. The test operations performed by packager are not logged to the Deployment Monitoring Console database (DMCDB). Available with Datical version 5.1 or higher.
Note If you enable rollback validation, you must provide rollback files (-rollback) for all SQL scripts starting from when you enable it. You do not need to provide files for SQL scripts that have already been packaged and deployed. |
disableTraceFile | SQL code files | Oracle only. Controls whether the Oracle trace file is used. Default value is false. The option to disable trace file is only available in Datical versions 5.3 and higher.
With tracefile turned on, Datical is able to detect and include the following additional SQL statement types during the CONVERT process (for Oracle Only): "create type", "create or replace type", "alter type", "drop type", "create materialized view", "alter materialized view", "drop materialized view", "create database link", "create shared database link", "create public database link", "create shared public database link", "drop database link", "drop public database link", "grant", "revoke", "insert", "update", "delete", select". |
packageOrderStrategy | SQL code files | Specifies a custom package order, one of:
|
skipCheckin | Project files, SQL code files | If this is not present or is set to false , Deployment Packager performs the final SCM operation to send changes from the local repository to the SCM server. To skip this operation, set to true .
|
ephemeralConnectionRetryTimeout | Backup (Azure SQL Managed Instance & Azure SQL DB only) | This setting defines an overall time (in minutes) that a Deploy Packager job should try to get a connection to the ephemeral database instance copy created for use in Azure SQL Managed Instance packaging. If the time expires and a successful connection cannot be made, Deploy Packager will fail. For more information see The ephemeralConnectionRetryTimeout property for Azure SQL Managed Instance |
Sample deployPackager.properties files
Documented example deployPackager.properties file
# This properties file controls the Datical DB deployPackager sqlScmSystem=git sqlScmLastImportID=421541c sqlScmBranch=master sqlScmPath=/home/developer/mySqlCode sqlScmSQLBaseDir=sql_code # the database backup restore location is on the db server. databaseBackupRestoreLocation= # Branch & Pipeline Specific Properties for Multiple Pipeline Projects # Settings for the JUL_2016 Datical Deployment Pipeline JUL_2016.sqlScmBranch=JUL_2016_SQL JUL_2016.sqlScmLastImportID=75782c #Settings for the AUG_2016 Datical Deployment Pipeline AUG_2016.sqlScmBranch=AUG_2016_SQL AUG_2016.sqlScmLastImportID=49628d #Settings for the PROD_STAGING Database Definition PROD_STAGING.sqlScmBranch=AUG_2016_SQL PROD_STAGING.sqlScmLastImportID=69371n
Sample deployPackager.properties file included in the product
A sample deployPackager.properties file is included in the DaticalDB installation in directory <datical-install>\DaticalDB\repl\scripts\
. You can copy it to each of your project directories and edit it for each project.
Copyright © Liquibase 2012-2022 - Proprietary and Confidential