Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Use the metadata.properties file to specify behavior during packaging. 

...

Overrides the project option enableSqlParser=true.  There is no effect if the project-level setting is enableSqlParser=false.  This property can be used in metadata.properties for folders that use packaging method DIRECT or SQLFILE.  See Using SQL Parser. 

Property

Values

Description

disablePropertySubstitution

allowRepackaging


true | falseTurns off interpretation of properties set in the changelog. See Setting Properties in the Project Changelog. disableSqlParsertrue | false
Note
iconfalse
titleThe SQL Parser and the DATA_DML packaging method

When using the DATA_DML packaging method, the SQL Parser is disabled by default for DML with versions 7.6 and higher.

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. 

contexts

 contextName[,contextName

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. No expressions Expressions are allowed. allowRepackagingdisablePropertySubstitutiontrue |   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.

rerunnabletrue | 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. 

  • Rerunnable scripts can be modified in place and repackaged.  They stay in their original directory and are not archived.
  • Non-rerunnable scripts can be packaged only once. During packaging the original scripts are moved from the original directory to an archive directory. They cannot be copied back and edited after packaging.  To modify non-rerunnable scripts, use the create / replace workflow. See Developer Workflows: Managing Changesets During Development and Test. 

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.

  • true - SQL code file is not archived. It can be repackaged.
  • false - SQL code file is archived. It cannot be repackaged.

If not set, the value is assigned based on its type (the folder where it is placed in SCM):

  • ddl - rerunnable=false
  • ddl_direct - rerunnable=false
  • data_dml - rerunnable=false
  • sql_direct - rerunnable=false
  • sql - rerunnable=false
  • procedure - rerunnable=true
  • package - rerunnable=true
  • packagebody - rerunnable=true
  • function - rerunnable=true
  • trigger - rerunnable=true
  • view - rerunnable=true

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:

  • archive=true and allowRepackaging=true
  • archive=false and allowRepackaging=false

See also Flexible Folder Names. When you use flexible folder names it is important to specify rerunnable correctly. 

packageMethodconvert | ddl_direct | direct | data_dml | sqlfile | storedlogic | ssis | changelog

Starting with Datical DB v5.0, specifies how to package the file, one of convert, ddl_direct, direct, data_dml, sqlfile, storedlogic, ssis. Packager further parses storedlogic files to determine their type, one of function, procedure, package, packagebody, trigger, view.  See Flexible Folder Names.

Use the changelog value when packaging Liquibase changelogs. They are processed differently than SQL scripts. See Packaging Liquibase Changelogs and Flexible Folder Names.

ignoretrue | falseDo 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 <database>.<schema>. Starting in version 5.4, you can use a wildcard for the schema: <database>.*.  This capability allows you to manage all SQL scripts for the database in a single folder. 

Note
iconfalse
titleQuoting and Casing Considerations When Setting the 'schemaName' property
  • In order to ensure a consistent deployment experience the casing defined for schema names in the Datical Project and the casing used to set this property MUST MATCH.  If they don't match, Deploy Packager will halt with an error
  • It is not necessary to quote schemaName values.  Quotes will be removed during Deploy Packager execution.
Warning
titleWarning

Do not  use schemaName if you are using databaseBackupMode=on_demand in deployPackager.properties with Datical DB versions 5.5 and lower.   (It is okay to use databaseBackupMode=on_demand in deployPackager.properties with Datical DB versions 5.6 and higher.)

ssisPkgNamefilenameName of an SSIS package file, including extension (.dtsv)ssisConfigfilenameName of an SSIS configuration file, including extension (.dtsConfig)ssisDestPathpathDestination directory under SSISDB in the SQL Server database. ssisDestTypeSQLHow deployed SSIS files are stored on the destination SQL Server. Default is SQL - store the files in the SQL Server database on the destination server. ssisPkgNamenameName of an SSIS package file (.dtsx).ssisProjectNamenameName of anSSIS project file (.ispac).ssisSupportFileDestPathnetwork-path

Windows shared drive destination for support files that accompany an SSIS package file (.dtsx). (example: \\SSIS-TEST\SSIS_SHARED) 

versionStrategydeployAll | deployLatest

Specifies how to deploy existing versions of rerunnable changesets if multiple versions are available to deploy. Values are not case-sensitive. 

  • deployAll - (default) deploy all eligible versions in the order they appear in changelog.xml. This has been the strategy used historically (before versioning). 
  • deployLatest - deploy only the latest eligible version. 

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).

folderOrderComma-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 deployPackager.properties file.

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

...

titleSample metadata.properties file
linenumberstrue
collapsetrue

...

Turns off interpretation of properties set in the changelog. See Setting Properties in the Project Changelog. 
disableSqlParsertrue | false

Overrides the project option enableSqlParser=true.  There is no effect if the project-level setting is enableSqlParser=false.  This property can be used in metadata.properties for folders that use packaging method DIRECT or SQLFILE.  See Using SQL Parser. 

Note
iconfalse
titleThe SQL Parser and the DATA_DML packaging method

When using the DATA_DML packaging method, the SQL Parser is disabled by default for DML with versions 7.6 and higher.


enableRollbackOnErrortrue | 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.

When enableRollbackOnError=false, Liquibase adds WHENEVER SQLERROR EXIT SQL.SQLCODE; into native tools. This indicates Liquibase will not rollback if an error occurs which allows failure scripts to still be partially committed. 

You may specify this property in the GUI or in the CLI during the deploy packager operation.


Info

sqlPlus only: enableRollbackOnError is set to true by default.
EdbPlus and ClpPlus only: enableRollbackOnError is set to false by default.


This setting was added in Liquibase Enterprise 8.4.


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. 

rerunnabletrue | 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. 

  • Rerunnable scripts can be modified in place and repackaged.  They stay in their original directory and are not archived.
  • Non-rerunnable scripts can be packaged only once. During packaging the original scripts are moved from the original directory to an archive directory. They cannot be copied back and edited after packaging.  To modify non-rerunnable scripts, use the create / replace workflow. See Developer Workflows: Managing Changesets During Development and Test. 

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.

  • true - SQL code file is not archived. It can be repackaged.
  • false - SQL code file is archived. It cannot be repackaged.

If not set, the value is assigned based on its type (the folder where it is placed in SCM):

  • ddl - rerunnable=false
  • ddl_direct - rerunnable=false
  • data_dml - rerunnable=false
  • sql_direct - rerunnable=false
  • sql - rerunnable=false
  • procedure - rerunnable=true
  • package - rerunnable=true
  • packagebody - rerunnable=true
  • function - rerunnable=true
  • trigger - rerunnable=true
  • view - rerunnable=true

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:

  • archive=true and allowRepackaging=true
  • archive=false and allowRepackaging=false

See also Flexible Folder Names. When you use flexible folder names it is important to specify rerunnable correctly. 

requireRollbacktrue | 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.

packageMethodconvert | ddl_direct | direct | data_dml | sqlfile | storedlogic | changelog

Specifies how to package the file, one of convert, ddl_direct, direct, data_dml, sqlfile, storedlogic. Packager further parses storedlogic files to determine their type, one of function, procedure, package, packagebody, trigger, view.  See Flexible Folder Names.

Use the changelog value when packaging Liquibase changelogs. They are processed differently than SQL scripts. See Packaging Liquibase Changelogs and Flexible Folder Names.

ignoretrue | falseDo 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 <database>.<schema>. Starting in version 5.4, you can use a wildcard for the schema: <database>.*.  This capability allows you to manage all SQL scripts for the database in a single folder. 

Note
iconfalse
titleQuoting and Casing Considerations When Setting the 'schemaName' property
  • In order to ensure a consistent deployment experience the casing defined for schema names in the Datical Project and the casing used to set this property MUST MATCH.  If they don't match, Deploy Packager will halt with an error
  • It is not necessary to quote schemaName values.  Quotes will be removed during Deploy Packager execution.


versionStrategydeployAll | deployLatest

Specifies how to deploy existing versions of rerunnable changesets if multiple versions are available to deploy. Values are not case-sensitive. 

  • deployAll - (default) deploy all eligible versions in the order they appear in changelog.xml. This has been the strategy used historically (before versioning). 
  • deployLatest - deploy only the latest eligible version. 

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).

folderOrderComma-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 deployPackager.properties file.

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

Code Block
titleSample metadata.properties file
linenumberstrue
collapsetrue
# 	
# 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.
#
#
# The following properties can be set in the metadata.properties file:
#
# disablePropertySubstitution - If 'true' - disables variable substitution performed by packager prior to packaging script.  Default value 'false'.
#
# disableSqlParser   - This is only for Oracle.  Overrides the project option enableSqlParser=true.  There is no effect if the project-level setting is enableSqlParser=false.  
#                      This property previouslycan controlledbe whetherused you can reuse a filename. The default value was 'false', but it is now deprecatedin metadata.properties for folders that use packaging method DIRECT or SQLFILE.
#
# labels archive            - DEPRECATEDOne startingor with Datical DB v4.37. Use rerunnable instead.
#               more labels that identify this set of changes so they can be easily identified and deployed as a group
#       This property previously controlled whether files in the data_dml directory get copied to the archive directory.  
#  labelName[,labelName...]
#
# contexts           - One or more context names to associate a changes Thewith defaultspecified valueenvironments.
was# 'true', but now it is deprecated. # # rerunnable         - Classify SQL scripts as rerunnable (true) or non-rerunnable (false). Use it in place of the [archive] and [allowRepackaging] properties contextName[,contextName...]
#
# allowRepackaging   - DEPRECATED starting with Datical DB v4.37. Use [rerunnable] instead.
#                      This Setproperty rerunnablepreviously tocontrolled 'true'whether or 'false':
#               you can reuse a filename. The default value was 'false', but it is now deprecated.
#
# archive           true - SQLDEPRECATED codestarting filewith isDatical notDB archivedv4.37. ItUse canrerunnable be repackagedinstead.
#                      This property previously controlled falsewhether files -in SQLthe codedata_dml filedirectory isget archived.copied Itto cannotthe bearchive repackageddirectory. # 
#                      If not set, the value is assigned basedThe ondefault itsvalue type (the folder wherewas 'true', but now it is placed in SCM):deprecated.
#
# rerunnable         - Classify SQL scripts as rerunnable (true) or non-rerunnable (false). Use it in place of the [archive] ddland - rerunnable=false[allowRepackaging] properties.
#                      Set rerunnable to  data_dml - rerunnable=false'true' or 'false':
#                          ddl_directtrue - rerunnable=falseSQL #code file is not archived. It can be repackaged.
#                 sql_direct - rerunnable=false #      false - SQL code file is archived. It cannot be repackaged.
#
#         sql - rerunnable=false #          If not set, the value is assigned based on its type (the folder where it is procedureplaced - rerunnable=truein SCM):
#                          packageddl - rerunnable=truefalse
#                          packagebodydata_dml - rerunnable=truefalse
#                          functionddl_direct - rerunnable=truefalse
#                          triggersql_direct - rerunnable=truefalse
#                          viewsql - rerunnable=truefalse
# #                      Important: although the useprocedure of archive and allowRepackaging are allowed, they are deprecated.
#  - rerunnable=true
#                    In addition, the following combinations of settingspackage now cause an error during packaging:- rerunnable=true
#                          archive=truepackagebody and- allowRepackagingrerunnable=true
#                          archive=falsefunction and- allowRepackagingrerunnable=falsetrue
#
#                          trigger - rerunnable=true
#      Also   you can use Flexible Folder Names. When you use flexible folder names it is important to specify rerunnableview correctly.
#- rerunnable=true
#
# packageMethod      - Specifies how to package the file. One of 'convert', 'ddl_direct', 'direct', 'data_dml', 'sqlfile', 'storedlogic', 'ssis'.
#              Important: although the use of archive and allowRepackaging are allowed, they are deprecated.
#         Packager further parses storedlogic files to determine their type, one of 'function', 'procedure', 'package', 'packagebody', 'trigger', 'view'.
#          In addition, the following combinations of settings now cause an error during packaging:
#             Use  the 'changelog' value when packaging Liquibase changelogs. They are processed differently thanarchive=true SQL scripts.and allowRepackaging=true
#    # ignore             - If 'true' - skip files in this directoryarchive=false and all subdirectories and do not process them.
#
# schemaName allowRepackaging=false
#
#                    - Schema nameAlso oryou comma-separatedcan listuse ofFlexible schemaFolder namesNames. #When you use flexible folder names it is important to specify rerunnable correctly.
#
#
# packageMethod      Use- eitherSpecifies ahow literalto valuepackage orthe afile. property.One The property must exist in the changelogof 'convert', 'ddl_direct', 'direct', 'data_dml', 'sqlfile', 'storedlogic'.
#                      IfPackager youfurther useparses fully-qualifiedstoredlogic objectfiles namesto indetermine SQLtheir scriptstype, theone schema names in the SQL scripts must match the schema names in the projectof 'function', 'procedure', 'package', 'packagebody', 'trigger', 'view'.
#                      PackagerUse returnsthe an'changelog' errorvalue ifwhen itpackaging encountersLiquibase achangelogs. schemaThey referenceare thatprocessed isdifferently notthan defined in the projectSQL scripts.
#
# ignore                     For multi-database projects set, schemaName in the form <database>.<schema>.
#                      Starting in version 5.4, you can use a wildcard for the schema: <database>.*.
#            If 'true' - skip files in this directory and all subdirectories and do not process them.
#
# schemaName         - Schema name or comma-separated list of schema names.
#           This capability allows you to manage all SQL scripts for the databaseUse ineither a singleliteral folder.value #
#            or a property. The property must exist in the changelog.
#          WARNING #           If you use fully-qualified object names in SQL scripts, the schema Donames notin the useSQL [schemaName]scripts ifmust youmatch arethe using databaseBackupMode=on_demandschema names in deployPackager.propertiesthe project.
# # versionStrategy    - Specifies how to deploy existing versions of changesets if multiple versions are available to deploy. #Packager returns an error if it encounters a schema reference that is not defined in the project.
#
#    Values are not case-sensitive.  #             For multi-database projects set, schemaName in the form <database>.<schema>.
#    deployAll - Deploy all eligible versions in the order they appear in changelog.xml. Default value. #   Starting in version 5.4, you can use a wildcard for the schema: <database>.*.
#                      This hascapability beenallows theyou strategyto usedmanage historicallyall (before versioning).
#        SQL scripts for the database in a single folder.
#
#                  deployLatest - deploy only the latest eligible version. 
WARNING
# #                     Do Ifnot versionStrategy isuse set[schemaName] toif anyyou otherare value, processing stops with an errorusing databaseBackupMode=on_demand in deployPackager.properties.
#
# versionStrategy    - Specifies how to deploy existing versions of changesets if multiple versions are available to deploy.
A# changeset is eligible to deploy if it meets criteria set in the deploy operation (label expression). # # # The following propertyValues isare only allowed in the root directory (sqlScmSQLBaseDir) and is not allowed in the subdirectories:
#
# folderOrdernot case-sensitive. 
#                  - Comma separated list of folder names to enforcedeployAll the- packageDeploy orderall ofeligible files.versions Thisin canthe beorder usedthey #appear in changelog.xml. Default value.
#                 when packageMethod ordering (deployPacakger property) is insufficient. # # ### Microsoft SQL Server ### # # SQL Server Integration Services (SSIS) relatedThis propertieshas #been #the ssisPkgNamestrategy used historically (before versioning).
#   - Name of an SSIS package file, including extension (.dtsv) # # ssisConfig         - Name ofdeployLatest an- SSISdeploy configurationonly file,the includinglatest extensioneligible (version.dtsConfig) 
#
# ssisDestPath       - Destination directory under SSISDB in the SQL Server database. # # ssisDestType  If versionStrategy is set to -any Howother deployedvalue, SSISprocessing filesstops are stored on the destination SQL Serverwith an error.
#                      A Defaultchangeset is 'SQL'eligible -to storedeploy theif filesit inmeets thecriteria SQLset Serverin databasethe ondeploy theoperation destination(label serverexpression).
#
#
ssisPkgName# The following property is only allowed in -the Name of an SSIS package file (.dtsx)
#
# ssisProjectName    - Name of anSSIS project file (.ispac)root directory (sqlScmSQLBaseDir) and is not allowed in the subdirectories:
#
# ssisSupportFileDestPathfolderOrder - #      - Comma separated list of folder names to enforce the package order of files. This can Windowsbe sharedused
drive# destination for support files that accompany an SSIS package file (.dtsx) #          when packageMethod ordering (deployPacakger property) is insufficient.
#
#
### Microsoft SQL Example: \\SSIS-TEST\SSIS_SHAREDServer ###
#

labels=
contexts=
rerunnable= 
packageMethod=
schemaName=
versionStrategy=
disablePropertySubstitution=

...