Specifying Properties in a Connection Profile

Note: The Connection Profile is optional. This data is not required for liquibase.properties to function successfully.

A connection profile contains the information that Liquibase needs to connect to a particular database. It resides in the text-based Liquibase properties file, liquibase.properties, along with other properties that rarely change. A connection profile eliminates the need to enter properties through the command prompt as parameters, saving you time and potential typographical errors.

Parameters that are entered at a command prompt override values that are specified in a connection profile.

Creating a connection profile

To create a connection profile, generate a new text file in your project Liquibase directory and name it liquibase.properties.

Note: The file can be named something other than liquibase.properties and reside in a different directory by using the --defaultsFile attribute every time you run a Liquibase command. For more information, see Working with Command Parameters.

Example Properties File

The following example properties file describes a connection profile for an Oracle database.

changelog-file: ../path/to/file/dbchangelog.xml
driver: oracle.jdbc.OracleDriver
url: jdbc:oracle:thin:@192.168.0.22:1521/orcl
username: PRO
password: password
referenceDriver: oracle.jdbc.OracleDriver
referenceUrl: jdbc:oracle:thin:@192.168.0.22:1521/orcl
referencePassword: password
liquibaseProLicenseKey: aeioufakekey32aeioufakekey785463214
classpath: ../path/to/file/ojdbc6-11.2.0.3.0.jar

Activating a Liquibase Pro License Key

To activate a Liquibase Pro license key, perform the following steps:

  1. Using a text editor, open the Liquibase properties file.
  2. Add liquibaseProLicenseKey: to the list of parameters.
  3. Specify your license key as the value, as the previous example shows.
  4. Save the properties file.

Properties

The values in a properties file must be specific to the database that it describes. Liquibase recommends configuring the properties file to include your driver, class path, and URL. For more information about property formats, see Liquibase Database Tutorials and select the appropriate database.

Note: Although Liquibase allows for the storage of user-authentication information (username and password) in the properties file, we recommend that you store user credentials in a secure credential repository or enter them in the CLI when running a command.

The following table identifies additional properties that can be specified in the Liquibase properties file.

Note: Some of these properties are optional. If it has the Optional tag underneath the definition, this data is not required for liquibase.properties to function successfully.

Property Definition
changelog-file Specifies the path to the changelog to execute.
driver Specifies the driver class name for the target database.
referenceUrl

Specifies the source database for performing comparisons.

Optional

username Specifies the username for the target database.
password Specifies the password for the target database.
referenceDriver

Specifies the driver class name for the source database.

Optional

url Specifies the database to use when making comparisons to the source database. Also known as the target.
referenceUsername

Specifies the username for the source database.

Optional

referencePassword Specifies the password for the source database.
liquibaseProLicenseKey Specifies the Liquibase Pro license key, if applicable. When added to the Liquibase properties file, liquibaseProLicenseKey eliminates the need to type the license key every time you enter a Liquibase command.
classpath Specifies the directories and jar files to search for changelog files and custom extension classes. To separate multiple directories, use a semicolon (;) on Windows or a colon (:) on Linux or MacOS.

changeExecListenerClass

=<ChangeExecListener.ClassName>

Specifies the custom ChangeExecListener implementation to use.

changeExecListenerPropertiesFile

=</path/to/file.properties>

Specifies properties for ChangeExecListener.

changeSetAuthor

Specifies the author of automatically generated changesets.

changeSetContext

Specifies the execution context to use for changesets in the generated changelog. Use a comma (,) to separate multiple contexts.

contexts=<value>

Specifies changeset Contexts to run.

currentDateTimeFunction=<value>

Overrides the current date time function used in SQL. Useful for unsupported databases.

databaseChangeLogLockTableName

=<name>

Specifies the Liquibase changelog lock table. Default value is DATABASECHANGELOGLOCK.

databaseChangeLogTableName

=<name>

Specifies the Liquibase changelog table. Default value is DATABASECHANGELOG.

databaseChangeLogTablespaceName

=<name>

Specifies the tablespace in which the DATABASECHANGELOGLOCK and DATABASECHANGELOG tables are created. Available for Oracle databases.

databaseClass=<custom.DatabaseImpl>

Specifies the custom database implementation.

dataOutputDirectory

Specifies the directory in which insert statement CSV files are maintained. Required by the generate-changelog command.

defaultCatalogName

Specifies the default catalog name for the database connection.

defaultSchemaName

Specifies the default schema name for the database connection.

delimiter=<string>

Sets the string that breaks up files that consist of multiple statements. Used with ExecuteSqlCommand.

diffTypes

Specifies the diff types to include in the changelog, expressed as a comma-separated list, from tables, views, columns, indexes, foreignkeys, primarykeys, uniqueconstraints, and data. If this value is null, the default types are tables, views, columns, indexes, foreignkeys, primarykeys, and uniqueconstraints.

Note:Available options depend on the Liquibase product, version, and plugins.

driverPropertiesFile

Specifies the location of the JDBC connection file whose properties the driver uses.

excludeObjects

Specifies objects to exclude from the changelog. Example filters: table_name, table:main_.*, and column:*._lock, table:primary.*.

includeCatalog=<true or false>

Includes the catalog in the generated changesets. Default value is false.

includeObjects

Specifies objects to include in the changelog. Example filters: table_name, table:main_.*, and column:*._lock, table:primary.*.

includeSchema=<true or false>

Includes the schema in the generated changesets. Default value is false.

includeSystemClasspath=<true or false>

Include the system classpath in the Liquibase classpath. Default value is true.

includeTablespace=<true or false>

Includes the tablespace of tables and indexes. Default value is false.

labels=<value>

Filters the changelog using Labels.

liquibaseCatalogName

Specifies the catalog name in which the Liquibase tables are located. The concept of a catalog varies between databases because not all databases feature catalogs. For more information, refer to your database documentation.

liquibaseHubApiKey

Specifies API key for authorization to Liquibase Hub.
liquibaseHubConnectionid

Identifies the target in which to record your data at Liquibase Hub. The property is available from within a project at https://hub.liquibase.com. Liquibase 4.4 and later support the following format: liquibase.command.hubConnectionId.
liquibaseHubProjectId

Identifies the project in which to record your data at Liquibase Hub. The property is available from within your account at https://hub.liquibase.com. Liquibase 4.4 and later support the following format: liquibase.command.hubProjectId.

liquibaseHubUrl

Specifies URL to Hub.

liquibaseSchemaName

Specifies the schema name in which the Liquibase tables are located.

log-file=<filename>

Sends logging messages to a file.

log-level=<level>

Specifies the execution log level as debug, info, warning, severe, or off.

outputDefaultCatalog=<true or false>

Specifies the catalog name that the SQL object references include, even if it is the default catalog.

outputDefaultSchema=<true or false>

Specifies the schema name that the SQL object references include, even if it is the default schema.

output-file=<file>

Specifies the target file for command-written output.

outputSchemasAs

Uses the names as schemaName instead of the real names on the diff-changelog command and generate-changelog command.

overwriteOutputFile=true

Forces overwriting the generated changelog/SQL files.

parameter.*

Passes properties that begin with a parameter as changelog parameters.

For example, setting parameter.active=true exposes an active=true changelog property.

promptForNonLocalDatabase

=<true or false>

Prompts if non-localhost databases are detected. Default value is false.

propertyProviderClass=<properties.ClassName>

Specifies the custom properties implementation.

referenceDefaultCatalogName

Specifies the reference database catalog.

referenceDefaultSchemaName

Specifies the reference database schema.

referenceSchemas=<name1,name2>

Specifies a comma-separated list of reference database schemas from which to include objects when running a command, such as snapshot, generate-changelog, or diff-changelog. Required when referencing multiple schemas in a command.

rollbackScript

Specifies the path to a rollback script that overrides the changelog rollback logic.

schemas=<name1,name2>

Specifies a comma-separated list of database schemas
from which to include objects when executing a command, such as snapshot, generate-changelog, or diff-changelog. Required when referencing multiple schemas in a command.

snapshotFormat

Specifies the file format when you run the snapshot command and snapshot-reference command.

sqlFile

Specifies the file in which SQL statements are stored.

strict=<true|false>

Specifies whether Liquibase fails with a validation error when the properties file, liquibase.properties, contains unknown or inapplicable properties. Default value is false.

Additional Liquibase Properties

The following table identifies additional properties that the Liquibase properties file supports in Liquibase 4.1 and later. To use them with an earlier version, set them as as java system properties, as the following CLI examples show:

  • Windows: set JAVA_OPTS=-Dliquibase.x=a -Dliquibase.y=b && liquibase --changelog-file=dbchangelog.sql update
  • Linux: JAVA_OPTS="-Dliquibase.x=a -Dliquibase.y=b" liquibase --changelog-file=dbchangelog.sql update
Property Definition

liquibase.ignoreRecycleBinWarning=<true|false>

Does not output the warning if the value is set to true, and if you connect to Oracle using a user that does not have access to the system recycle bin.

liquibase.shouldRun=<true|false>

Defines whether Liquibase will run. If the value is set to false, Liquibase will not run.

liquibase.outputLineSeparator

Specifies the line separator for the output. Default value is set to OS default one.

liquibase.changeLogLockWaitTimeInMinutes

Specifies a number of minutes to wait for the changelog lock to be available. Default value is: 5.

liquibase.changeLogLockPollRate

Specifies a number of seconds to wait between checks to the changelog lock when it is locked. Default value is: 10.

liquibase.convertDataTypes

Defines whether Liquibase converts to/from STANDARD data types. Applies to both snapshot and update commands.

liquibase.outputEncoding

Specifies the encoding to output text in. Default value is set to file.encoding system property or UTF-8.

liquibase.generateChangesetCreatedValues

Defines whether Liquibase includes a 'created' attribute in diff/generate-changelog changesets with the current date time. Default value is: false.

liquibase.autoReorg

Defines whether Liquibase automatically includes REORG TABLE commands when it is needed. Default value is: true.

liquibase.diffColumnOrder

Defines whether Liquibase compares column order in the diff operation. Default value is: false.

Liquibase.alwaysOverrideStoredLogicSchema

Defines whether the procedure schema is forced to the default schema if no schemaName attribute is set and when an SQL is generated for createProcedure. Default value is: false.

liquibase.generatedChangeSetIdsContainDescription

Defines whether Liquibase includes the change description in the id when generating changesets. Default value is: false.

liquibase.shouldSnapshotData

Defines whether Liquibase makes snapshots of data by default. Default value is: false.

liquibase.filterLogMessages

Defines whether Liquibase filters log messages for potentially insecure data. Default value is: true.

liquibase.hub.mode

Controls the level of data sent to Liquibase Hub. The values are all, meta, or off. Default value is: all.

liquibase.pro.markUnusedNotDrop

Calls markUnused if a column will be dropped in diff-changelog and if the value if set to true. Default value is: false.

liquibase.pro.synonyms.drop.public

Does not drop public synonyms in diff-changelog or drop-all if the value is set to false. Default value is: true.

liquibase.pro.sql.inline

Generates changesets with SQL-based changes embedded instead of saving them to an external file if the value is set to true. Default value is: false.

Related Links