Liquibase Enterprise was formerly known as Datical DB.

Liquibase Enterprise Labels

Owned by Former user (Deleted)
Last updated: Jan 29, 2024 by Lora Griffin
4 min read

Overview of Labels

A label is a string that is stored on a changeset. Labels are used to track and manage changes as they move through the release pipeline. 

Label Character Restrictions

Label names may include only the following characters:

  • letters (upper and lower case, including UTF-alphanumeric chars such as ö and ñ)

  • numbers

  • dashes ( - )

  • underscores ( _ )

  • periods (.)

Using any other character may cause failure during packaging and other operations. In particular, never use the equals character ( = ) in a label or SCM checkin comment.

When setting and evaluating labels, Liquibase Enterprise will substitute all non-UTF-8 alphanumeric characters (with the exception of - and .) with the '_' symbol.

Specifying Labels

Labels are first added when SQL scripts are packaged. Some labels are added automatically during Datical operations. 

Where

How

Where

How

Project

Static assignment. These labels are assigned at all steps and for all operations. Use the Datical GUI or edit the datical.project file. 

May be a label expression: either a comma-separated list or an expression that uses !, AND, OR, and parentheses.  See Label Expressions below. 

DbDef / Step definition

Static assignment. When a changeset is deployed to this step, must have the label or labels specified. Use the Datical GUI or edit the datical.project file. 

May be a label expression: either a comma-separated list or an expression that uses !, AND, OR, and parentheses.  See Label Expressions below. 

Note

If you are using pipelines, the pipeline name must be the first label in the list. 



Check in to SCM

NOTE: This item is only relevant for Liquibase Enterprise/Datical DB customers who use deploy packager.  (Not available in Liquibase Business.)

Use square brackets in the check-in comment to include labels. It is a common practice to include the issue-tracking ticket number at check-in. The labels are added during packaging. Any changesets produced by packaging get the labels specified.   

git commit -m "[JIRA-1115][Add columns to Books table]"



As of the 7.9 Release of Liquibase Enterprise, the pattern that denotes labels in commit messages can be defined by the user.  Please see the description of the commitMsgLabelRegexp property on Use the Required deployPackager.properties File

Packaging

NOTE: This item is only relevant for Liquibase Enterprise/Datical DB customers who use deploy packager.  (Not available in Liquibase Business.)

Labels are added to changesets during packaging by all of the following methods. 

Automatic: the following labels are added automatically during packaging. 

  • SQL script file name

  • Pipeline label (as specified in the REF context DbDef)

metatdata.properties file

  • Use the label property to specify one or more additional labels to add during packaging. Use a comma-separated list for multiple values. Expressions are not supported. 

deployPackger.groovy command-line option

  • Use the labels= option to add one or more additional labels to add. Use a comma-separated list for multiple values. Expressions are not supported. 

Operations

The following operations allow you to work with labels.

  • forecast - add labels during the operation

  • deploy - add labels during the operation

  • modifyChangeSet - add and remove labels on changesets directly

  • diffChangeLog - add labels during the operation



Label Expressions

Label expressions can be used only in the project, a DbDef or with CLI parameter options.

You can use a comma-separated list or an expression, but not both. 

Note that label expressions must be enclosed in quotes when used as CLI parameter options. 

Examples:

--searchLabels="(cliLabel1 AND cliLabel2) AND (dbdefLabel1 OR dbdefLabel2 OR dbdefLabel3)"

--labels="cliLabel1, cliLabel2"

Comma-Separated List

When a comma-separated list of labels is set on a DbDef, a changeset must have at least one of the labels in the list in order to be deployed to the step.

Syntax example:

--labels=cliLabel1,cliLabel2

When using a comma-separated list, there should be no space following the comma.

Expression Elements

! - (exclamation point) - NOT

AND - logical AND

OR - logical OR

() - (parentheses) - grouping 

Expression Examples

Labels are referred to by name in expressions. In the table, mylabel, yourlabel, hislabel, and herlabel are example labels. 

Expression

Description

Expression

Description

mylabel

Changeset must have mylabel to be deployed to this step.

mylabel, yourlabel

Changeset must have either mylabel or yourlabel to be deployed to this step.

mylabel OR yourlabel

Changeset must have either mylabel or yourlabel to be deployed to this step.

mylabel AND yourlabel

Changeset must have both mylabel and yourlabel to be deployed to this step.

!mylabel

Changeset must not have mylabel to be deployed to this step. 

!(mylabel OR yourlabel)

Changeset must have neither mylabel nor yourlabel to be deployed to this step. 

!(mylabel AND yourlabel)

Changeset may must have either mylabel or yourlabel, but not both, to be deployed to this step. 

mylabel AND !(herlabel OR hislabel)

Changeset must have mylabel but not herlabel or hislabel to be deployed to this step. 

Label Usage Practices

Labels can be used in several ways:

  • Group related database changes

    • group scripts by development ticket (JIRA-1115)

    • group scripts by release (currentRelease)

  • Deploy changes selectively

    • by script name (create_table_orderentry.sql)

    • by ticket number (JIRA-699)

    • by release (currentRelease)

  • Track Deployed Changes

    • Labels are tracked in the Deployment Monitoring Console Database (DMCDB). The Datical Management Console (DMC) provides views of operations by label. 

  • Manage workflow in the release pipeline

    • Labels on DbDefs enable or disable change promotion through the release pipeline. Examples: pass_unit_test, pass_feature_test, pass_manual_test, pass_uat.

    • Examples: pass_unit_test, pass_feature_test, pass_manual_test, pass_uat

  • Modify Changeset labels

    • Can update a label on a group of changesets

    • Example is 2 parts:

      • Add new label: hammer modifyChangeSet --action=ADD --modifyLabels=newlabel --searchLabels=MyScriptName123.sql

      • Remove old label: modifyChangeSet --action=REMOVE --modifyLabels=oldlabel --searchLabels=MyScriptName123.sql

Pipelines and DbDef Labels

If you choose to use pipelines within a project, you need to make the pipeline name the first label for every DbDef in the pipeline. 

Pipeline merges rely on the pipeline name being the first label on each DbDef. 

Errors

If you create an invalid expression for the project or the DbDef, you get an error during a status operation or during deployment:

Failed to get Liquibase Change Set Statuses Cannot parse expression <expression> Cannot parse expression <expression>



Copyright © Liquibase 2012-2022 - Proprietary and Confidential