Using Properties

Property values are defined in the changelog.xml file. Once defined, properties can be added to scripts and to the datical.project file to provide variability across environments for Liquibase Business.

Create property statements in the changelog. Use context= and label= to set up the conditions where you intend the different values to be used.
Write a SQL script that uses a variable to reference the property.
Deploy the changeset. During and deploy you can specify values for context and labels attributes. The changesets with matching contexts or labels are used.

Setting Properties in the Datical DB GUI

In the Datical DB GUI, do the following:

Open a project
Click the Settings tab
Open the Change Log Property Substitution section.
Click Manage Properties.
Add or edit property keys and values, along with the contexts and labels to use to determine when to apply the property substitution.
Note: Property statements that use the same name and value must also have a context or label set to differentiate them. That difference expresses the conditions where each value is used.
You cannot create more than one property setting for the same condition (contexts and labels settings).
Click Save.

Note that you can also edit the changelog.xml using a text editor if that is more convenient that using the GUI.

Property Syntax

Create property statements in the changelog. Use context= and label= to set up the conditions where you intend the different values to be used.
Write a SQL script that uses a variable to reference the property.
Deploy the changeset. During deploy you can specify values for context and labels attributes. The changesets with matching contexts or labels are used.

Appearance in the Changelog

Use GUI to create properties (or edit the changelog.xml using a text editor if that is more convenient). Differentiate properties with the same name by setting different values and contexts. Use the context to specify the environments where the values are applied.

In the following code example, the context property is used to set SCHEMA_NAME to different values (schema_alpha for the DEV context, schema_beta for the TEST context).

Property Definitions in the Changelog

<!-- properties for different schema -->
<property context="DEV" name="SCHEMA_NAME" value="schema_alpha"/>
<property context="TEST" name="SCHEMA_NAME" value="schema_beta"/>

Syntax in SQL Scripts

Use the following form where you want to substitute the value of a property in the script:

${property-name}

Use with Oracle Databases

It is common to host multiple environments on a single Oracle instance. Properties can be used for several purposes. Some examples are:

Schemas - point to the desired copy of a schema. Multiple copies might exist on the same instance.
Storage options - such as TABLESPACE
Sequences - different settings for startsWith and incrementBy, depending on environment

Example Scenario

Normally a workflow through DEV > TEST > QA > PROD uses the same schema name at each step. However, if in DEV the schema is named SCHEMA1 and in QA it is named SCHEMA2, you could set up property statements to give SCHEMA_NAME a different value depending on the context where a changeset is deployed.

Create two property statements in the changelog. Use the same name but different values (value=) and deployment conditions (in this case, context=).
Property Definitions in the Changelog
```

<property context="DEV" name="SCHEMA_NAME" value="SCHEMA1"/>
<property context="QA" name="SCHEMA_NAME" value="SCHEMA2"/>
```
Write the SQL to use the property name rather than a literal schema name.
SQL Script Using a Property
```
CREATE TABLE "${SCHEMA_NAME}"."MYTABLE"
   (MYCOLUMN VARCHAR(100)
   );
```
Deploy. The value used for ${SCHEMA_NAME} is driven by the difference in the context= attribute in the property statements.
- In the DEV database, the table is named SCHEMA1.MYTABLE
- In the QA database, the table is named SCHEMA2.MYTABLE

Using Properties for Schema Names

You can use properties for the schemaName attribute in the following places:

datical.project file

You may use properties in the managed-schema names. Here is an example:

Schema specification in datical.project

SCHEMA1${ENV}
SCHEMA2${ENV}

To use this capability, the ENV property in the previous example needs to have values supplied for it. Errors are returned during packaging if a schema name does not match a schema in the database.

Set the ENV property in the changelog. In this case, the context property determines the value to use for ENV.

<property context="DEV" name="ENV" value="_DEV"/>
<property context="QA" name="ENV" value="_QA"/>

The following database schema must exist in the corresponding managed databases:

DEV Database:
SCHEMA1_DEV
SCHEMA2_DEV
 
QA Database:
SCHEMA1_QA
SCHEMA2_QA

How and When Properties are Interpreted

Properties are evaluated and values substituted during the following operations with Liquibase Business:

Deploy

Property Substitution During Deploy

When you set a property to be interpreted for a context, then the property is interpreted when changes are deployed to the context.

<property context="DEV" name="ENV" value="_DEV"/>
<property context="QA" name="ENV" value="_QA"/>

Setting Properties in the Changelog for Liquibase Business