Use the metadata.properties
file to specify behavior during packaging.
Sample File
A sample metadata.properties
file is installed with Datical DB in <install-dir>/repl/scripts
.
Placement and Precedence
The metadata.properties
file applies to all files and subdirectories in the directory where it is found, including the root directory for SQL scripts. Additional metadata.properties
files can be used in the subdirectories. A property set in a subdirectory overrides the same property set in a parent directory.
Properties
Table: metadata.properties file
Property | Values | Description |
allowRepackaging | true | false | Deprecated starting with Datical DB v4.37. Use rerunnable instead. Starting with Datical DB v4.21, this property controls whether you can reuse a filename. The default value is false. |
archive | true | false | Deprecated starting with Datical DB v4.37. Use rerunnable instead. Starting with Datical DB v4.21, this property controls whether files in the data_dml directory get copied to the archive directory. The default value is true. |
contexts | contextName[,contextName...] | One or more context names to associate a changes with specified environments. Multiple values must be separated by commas. Expressions are allowed. |
disablePropertySubstitution | true | false | Turns off interpretation of properties set in the changelog. See Setting Properties in the Project Changelog. |
disableSqlParser | true | false | Overrides the project option |
enableRollbackOnError | true | false | When enableRollbackOnError=true, Liquibase adds WHENEVER SQLERROR EXIT FAILURE ROLLBACK; into native tools which rolls back all of the possible rollback changes in case there is a failure. This prevents scripts from partially deploying. You may specify this property in the GUI or in the CLI during the deploy packager operation. sqlPlus only: enableRollbackOnError is set to true by default. EdbPlus and ClpPlus only: enableRollbackOnError is set to false by default. |
labels | labelName[,labelName...] | One or more labels that identify this set of changes so they can be easily identified and deployed as a group. Multiple values must be separated by commas. No expressions are allowed. |
rerunnable | true | false | Starting with Datical DB v4.37, use this property to classify SQL scripts as rerunnable (true) or non-rerunnable (false). Use it in place of the archive and allowRepackaging properties.
Stored logic scripts are usually rerunnable as they perform CREATE OR REPLACE operations and can therefore be run multiple times and produce the same result (they are idempotent). Set rerunnable to true or false.
If not set, the value is assigned based on its type (the folder where it is placed in SCM):
Important: although the use of archive and allowRepackaging are allowed, they are deprecated. In addition, the following combinations of settings now cause an error during packaging:
See also Flexible Folder Names. When you use flexible folder names it is important to specify |
requireRollback | true | false | During the packaging process, it verifies whether SQL scripts have corresponding -rollback or _rollback files for all scripts affected by the metadata.properties configuration. By default, this validation is set to false. |
packageMethod | convert | | Starting with Datical DB v5.0, specifies how to package the file, one of Use the |
ignore | true | false | Do not process files in this directory and all subdirectories. See Flexible Folder Names. |
schemaName | Schema name or comma-separated list of schema names. Use either a literal value or a property. (If using a property, it must exist in the changelog, see Setting Properties in the Project Changelog). If you use fully-qualified object names in SQL scripts, the schema names in the SQL scripts must match the schema names in the project. Packager returns an error if it encounters a schema reference that is not defined in the project. For multi-database projects set, schemaName in the form Warning Do not use | |
versionStrategy | deployAll | deployLatest | Specifies how to deploy existing versions of rerunnable changesets if multiple versions are available to deploy. Values are not case-sensitive.
If versionStrategy is set to any other value, processing stops with an error. A changeset is eligible to deploy if it meets criteria set in the deploy operation (label expression). |
folderOrder | Comma-separated list of folders | Specified only in the metadata.properties file at the top of the SQL code tree. That directory must be the one specifed by the sqlScmSQLBaseDirproperty in the Provide a list of directories, in the order you want them packaged. Files from these directories are pulled to the front of the packaging order in front of any other folders in the packaging job. See Custom Packaging Order. |
Sample metadata.properties file
Assigning Labels and Contexts
You can automatically assign labels and contexts to changesets is by using the labels property and contexts property.
# This properties file controls label and context values on Deployment Packager generated change sets labels=label1,label2,label3 contexts=QA,PERF_TEST,UAT
Enabling Repackaging
The allowRepackaging property has been deprecated. Use the rerunnable property instead.
If for future scripts you want to be able to repackage the without changing the filename and do not want the script to be archived, set rerunnable=true
in the metadata.properties folder. The Deployment Packager then ignores the earlier version of this file and repackages it as a change set with a higher version number than the previous version. If rerunnable is not set, the Deployment Package ignores any files already packaged and moves them to the archive folder. You cannot re-use the same script name unless you are using rerunnable=true.
Note: The new script needs to account for what was already deployed by the older script.
For example,
- You package a script that creates a table.
- You want to change the script and repackage it. The changed script still creates the same table.
The changed script needs to drop the table before re-creating it.
Using schemaName with Multi-schema and Multi-database Projects
Projects that use multiple schemas require that that changesets include a schema specification for object changes.
Multi-database projects are also multi-schema. Each database may have multiple schema. Use the wildcard ( * ) for the schema in the schemaName
attribute to manage the projects using a database folder instead of a folder per schema.
During deployment, Deployment Packager evaluates the schemaName property. Evaluation behavior varies with the type of script as follows:
- If a sql script (ddl directory) does not specify a schema name for an object, the first schema listed in the schemaName property is used. Fully-qualified object names are considered valid, even if they use a schema name that does not match the schemaName setting.
- If a stored-logic script (function, package, packagebody, procedure, trigger, view directories) specifies a schema name for an object that does not match the first schema in the schemaName list, an error is returned.
- If a directly-executed script (sql, sql_direct directories) specifies a schema name for an object, the object is deployed to the schema specified in the script. The script setting overrides the schemaName property setting. However, the ChangeLog entry shows the the first item in theschemaName list.
Note
metadata.properties
, packaging fails with an error. Schema cannot be specified for single-schema projects. The schemaName property is evaluated only for some types of scripts, corresponding with the script directories:
Evaluated | Not evaluated |
---|---|
data_dml ddl ddl_direct function package packagebody procedure sql sql_direct (*see note about Microsoft SQL Server below) trigger view | sqlplus |
*For Microsoft SQL Server scripts must use fully qualified object names and references in the sql_direct folder, unless your schema is dbo AND dbo is set as the default schema for your Datical user.
For examples, see near the bottom of How To: Leverage the "metadata.properties" file.