Liquibase Enterprise was formerly known as Datical DB.

Configuring Project Settings

Project settings define aspects what the project manages (schema) and how operations behave (forecast, deploy, rollback, snapshot, diffChangelog). 

How to Change Project Settings

  • Use the GUI or CLI tool to change project settings for a project defined on your local system where Datical DB is installed.
  • Use Datical Service to change project settings for a project that was created on or imported into Datical Service.


ToolMethodFigure
GUI

Select a project in the Deployment Plans list, then click the Settings tab. 

CLI

Go to the project directory, then execute commands. The properties in the CLI column show properties that you manage through the hammer set and hammer show commands. 

datical.project In rare cases a setting must be set by hand. There is no setting in the GUI or command in the CLI. Use a text editor to edit the datical.project file. 

Options are set in the dbproject element. 

Sample datical.project file
<?xml version="1.0" encoding="ASCII"?>
<dbproject:Project xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:dbproject="http://datical.com/db/project/1.0" name="SampleProject" storedLogicExternal="true" deployThreshold="stopOnError" rowsPerBatch="10000" enableCompression="false" runtimeCredentials="false" multiSchema="false" dbSchemaDefinition="project" schemaSelectionStep="QA" enableRowCount="true">
  <dbDefs xsi:type="dbproject:PostgresqlDbDef" name="postgres" driver="org.postgresql.Driver" hostname="192.168.0.135" port="5432" username="admin" password="ZGVtbw==" contexts="REF" environment="DEV" database="postgres"/>
  <dbDefs xsi:type="dbproject:PostgresqlDbDef" name="Hotfix Step" driver="org.postgresql.Driver" hostname="postgres" port="5432" username="datical" password="YXNkZg==" database="postgres"/>
  <dbDefs xsi:type="dbproject:PostgresqlDbDef" name="QA" driver="org.postgresql.Driver" hostname="localhost" port="5432" username="admin" password="ZGVtbw==" contexts="QA" environment="QA" database="QA"/>
  <plans name="MainRelease" databaseDefs="//@dbDefs[name='postgres'] //@dbDefs[name='QA']"/>
  <plans name="Hotfix" description="" databaseDefs="//@dbDefs[name='Hotfix%20Step']"/>
  <changelog href="Changelog/changelog.xml#//@databaseChangeLog"/>
  <DMCDB xsi:type="dbproject:PostgresqlDbDef" name="DMCDB" driver="org.postgresql.Driver" hostname="localhost" port="5432" username="admin" password="ZGVtbw==" defaultSchemaName="daticalDMC" dbDefType="dmc" database="daticaldmc"/>
  <schemas name=""/>
</dbproject:Project>


Project Settings

Category (GUI)DefaultDescription

CLI
(properties)

Schema Management
Single Schema vs Multi-SchemaN/A

During project creation, choose whether to manage a single schema or multiple schema in the project. 

  • Single schema: Project manages objects in a single schema.
    • The databaseChangeLog table is kept in the managed database schema.
  • Multi-schema: Project manages objects in multiple schema.
    • The databaseChangeLog table is kept in a separate tracking schema that you choose or create.

It can be helpful to create a multi-schema project even if the project will manage one schema. It allows you to put the databaseChangeLog table in a schema other than the managed schema. 


Schema to be managed are in multiple databases (SQL Server Only)NoMulti-Database project, SQL Server only. 
Select Schema From:
Database that contains the schema. Select a database from the list. 
Managed Schema

Click Configure to select the schema to manage: one for single-schema projects, a list for multi-schema projects.

If you checked the "multiple database" option, use the form database.schema in the Select Schema from list. 


Tracking Schema
Click Configure to select the schema to use for the tracking database. The tracking database records operations performed on the project.
Level at which Database Schema are specifiedDeployment Plan

You can choose only for single-schema projects. Multi-schema projects are set to use Deployment Plan. 

  • Deployment Plan - select when schema names are the same across the databases for each step.
  • Deployment Step - select when schema names differ across the databases for each step.

Snapshot & Diff Settings
  • Externalize Stored Logic
True

Place stored logic in external files rather than the changelog during the operation. If set to false, place them in the changelog. 

Note: if set to false, you may encounter excessive memory usage.  If you do, see Use Less Memory When Reloading Plan in Preferences 

externalStoredLogic

[true | false]

  • Enable Accelerator for Oracle
FalseThis was useful in some environments when network bandwidth was a limiting factor (speed, contention, geographic separation). It worked by compressing results on the database server before sending them.  The accelerator/compression driver was available with versions 7.15 or lower.  It has been deprecated with versions 7.16 and higher.

Rows per Batch [10000]

10000When using the Accelerator for Oracle, this specified the maximum number of rows to be processed at one time. If forecast or snapshot operations encountered memory errors, lowering this value could help.  The accelerator/compression driver was available with versions 7.15 or lower.  It has been deprecated with versions 7.16 and higher.


  • Mark Columns as Unused...
False

Oracle only. Determine how to manage dropped columns.

  • False - drop the column (set change type to dropColumn)
  • True - mark the column as unused (set change type to markUnused). 

Deployment Settings

Forecast/Deploy

  • Require options for Forecast and Deploy
False

If set to true, the operation fails unless contexts and labels are specified. At least one of each must exist in the changesets being forecast or deployed. 

  • Labels can be set on a project and a step
  • Contexts can be set on a step.

requireOptions

[true | false]

  • Automatically generate SQL for Forecast, Deploy, and Rollback
FalseIf true, generate the SQL code used for the operation. 

autoGenSQL

[true | false]

  • Limit Forecast Profiling
False

If set to true, limit forecasting to only those objects affected by the changes. Otherwise profile all objects in the target database schema.

Note that some forecast and post-forecast rules may be skipped when this is true.

limitForecastProfiling

[true | false]

Oracle SQL*Plus Settings
  • Enable Oracle SQL Parser
False

If set to true, use the SQL Parser on native Oracle SQL scripts (ddl_direct, sql, and sql_direct folders). 

See Using SQL Parser

N/A
  • Forecast Data Modification Changes - DML 
FalseIf set to true, forecast whether DML changes will be successful (Oracle only).

forecastDML

[true | false]

  • Set DDL_LOCK_TIMEOUT Value [0]
FalseOracle only: Set the time in seconds to wait for a locked database to become available. 
  • Set NLS_LANG Parameter
False

Sets the NLS_LANG environment variable on the system where Datical DB is installed when Forecast and Deploy operations are executed for the project. This setting does not persist in the environment after the operation completes.

See Writing SQL Scripts for Datical DB to learn more about when and how to use the NLS_LANG environment variable or project setting. 

To set the variable:

nlsLang "<valid_locale.valid_charset>"

To clear/unset the variable

nlsLang ""

Collect Row Counts During Forecast & Deploy
  • Exact  

Collect accurate row counts using table scan. This method may be time consuming for large tables

enableRowCount

[exact | approximate | disabled]

  • Approximate

Collect estimated row counts using statistics. Uses database statistics as the source of information. You need to make sure the statistics are available and updated. The time saved varies, but can be significant for very large tables.

See Settings for Collecting Row Counts for the collection method for each database type. 


  • Disabled

Do not collect row counts.

Deployment Threshold

One of:

  • Stop Deployment on Validation Error
  • Stop Deployment on Validation Warning
  • Always Deploy (NOT RECOMMENDED)
ErrorSet threshold condition for stopping a deployment: on error, on warning, or none (always deploy). 

deployThreshold

[stopOnError | stopOnWarn | deployAlways]

Stored Logic Validity Check

One of:

  • Disabled - Do not perform the Stored Logic Validity Check
  • Limited - Compile and validate objects targeted by a Deployment and their dependencies
  • Local Schema - Compile and validate objects in all schemas specified in the deployment plan
  • Global - Compile and Validate Objects in All Accessible Schema
Local

Determines whether and how to perform a validity check for stored logic. A validity check compiles the stored logic and validates it against the database objects. Validation fails if the stored logic references database objects incorrectly.

  • Forecast operations: validity check is not performed.
  • Deploy operations: validity check is performed after deployment. 
  • Package operations: validity check is performed as part of the deployment to REF. 

The Limited mode is recommended when environments are known and expected to have a large number of stored logic objects or persistently invalid stored logic objects. In the Limited mode, DaticalDB will only compile the stored logic objects that are determined to be targeted by changes included in the deployment, which may lead to significant performance improvements for deploy operations.

However, for Oracle environments, objects that are valid after a deployment may be reported as invalid on the Deploy Report in some cases. This can occur when DaticalDB is unable to determine that the changes in the deployment are associated with the invalid object.

For this reason, it is not recommended to use storedLogicValidityAction=FAIL when storedLogicValidityCheck=LIMITED for Oracle.

See also: Stored Logic Validity Check details

storedLogicValidityCheck

[disabled | limited | local | global]

  • Fail Deployments that produce new invalid object errors. 
Warn

If a Stored Validity Check is performed (storedLogicValidityCheck or invalidsCheck), this storedLogicValidityAction option determines what happens when stored logic objects are found to be in an INVALID state.

Both existing objects already in the database and new objects being deployed are checked.  The VALID/INVALID state is checked prior to the deployment and then checked again after the deployment. The before and after validity state results are compared to determine whether a change of state was affected by the current deployment. 

  • warn - print WARN message and continue
    • New objects that have INVALID state - print WARN message
    • Existing objects that have INVALID state - print WARN message
  • fail - print WARN or ERROR message, depending on object state
    • New objects that have INVALID state - fail and print ERROR message
    • Existing objects that have INVALID state and were not affected by the current deploy operation - print WARN message
    • (7.7 & later) Existing objects that have INVALID state and were affected by the current deploy operation - fail and print ERROR message

If you are using storedLogicValidityAction=fail, we recommend setting storedLogicValidityCheck to either Local or Global (not Limited). 

Also note that there is a fix related to storedLogicValidityAction=fail in version 7.13 and higher.

Package operations: if the validity check action is set to fail and the validity check fails after deployment to REF, the package operation fails with an error and the database is restored to its state before the package operation was started. 

See also: Stored Logic Validity Check details

storedLogicValidityAction

[warn | fail]

Deployment Mode
  • Full Deploy - Perform Change Simulation and Rules Validation Before Deploying Change Sets
  • Quick Deploy - Only Deploy Change Sets
FullDetermines whether to perform an internal forecast operation before deploying. If the internal forecast fails, the deploy operation does not run. 

deployMode

[full| quick]

Credential Management
  • Specify Database Credentials at Operation Runtime
False

By default (false) database credentials are saved in the project file.

When set to true, any previously stored passwords are removed from all DbDefs (steps) in the project. You then use environment variables, CLI options, or user prompts to provide database credentials when an operation is run on the step. 

This project setting determines credential-checking for all databases used by the project.

  • All managed databases in the project (dbdefs)
  • Deployment Monitoring Console database (DMCDB) for the project. The project must be registered with a DMCDB.

Credentials are checked every time an operation accesses a database. All operations require credentials (package, forecast, deploy, rollback). 

We strongly recommend to use runtime credentials because it is more secure than stored credentials (due to the possibility of the stored password being decoded).

runTimeCredentials

[true | false]

DMC Database

Message shown is one of the following:

  • DMC Database is not configured
  • DMC Database is configured to connect to <URL> using user <username>
    Project is registered in the DMC Database

Configure DMC DBN/A

Click Configure DMC DB to configure the DMCDB database to use and provide credentials for the project to use when accessing it. Normally a DMCDB is used by all projects in an enterprise or large organization. 

We strongly recommend to use runtime credentials because it is more secure than stored credentials (due to the possibility of the stored password being decoded).


Register ProjectN/AClick Register Project to register this project with the configured DMCDB. Once the project is registered, all operations on the project are logged in the DMCDB. 
Clear DMC DB ConfigurationN/AClick Clear DMC DB Configuration to clear any previously configured connection and credentials information for DMC DB or the older Audit DB.   
Force SyncN/AClick Force Sync to force a re-sync/re-base to DMC DB using the files currently active in the workspace.forceSync
Release Labels
Manage Release LabelsN/A

Click Manage Release Labels to add, edit, or remove labels that are set for the project.  All steps and operations share these labels. Note that other labels may be set during change packaging and deployment. 

Labels and contexts can also be set on a step. Set them when you create a step or click Edit Connection for the step. 

modifyChangeSet
Change Log Property Substitution
Manage PropertiesN/AClick Manage Properties to add, edit, or remove properties set in the changelog. Typically properties are used along with property settings for deployment packager, especially the properties set in metadata.properties. 
  • Reverse Substitute During diffChangelog
FalseWhen set to true, the properties are used in diffChangelog operations. 

Deploy with Options

You can override project options during deployment operation by specifying Deploy with Options. 

See Deploying Changes for the list of options that can be overridden.  

Preferences

To access other preferences:

  1. Open the Datical DB GUI
  2. Select File > Preferences
  3. Select Changelogs in the left pane. 
Changelog PreferenceDefaultDescription
Check logicalFilePath attribute on loadOn
Allow keywords to differ only in case (NOT RECOMMENDED)Off
Use Less Memory When Reloading PlanOff

Turn on if you encounter low-memory problems when using the GUI. Typically the following conditions may trigger excessive memory usage:

  • Changelog is large
  • Changelog contains large numbers of SQL statements.  This can happen when Externalize Stored Logic is not enabled for the project.  






Copyright © Liquibase 2012-2022 - Proprietary and Confidential