Specifying Properties in a Connection Profile

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

The liquibase.properties file 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. The liquibase.properties file 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 liquibase.properties.

Creating a liquibase.properties file

To create a the file, 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 liquibase.properties file works 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

Note: You do not need to specify a classpath for pre-installed drivers in the liquibase/internal/lib directory or for drivers you placed in the liquibase/lib directory. If placed your database's JDBC JAR file in a different directory, you must specify the path: classpath:../<path_to_drivers>/<db_jar_name>.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. For more information about property formats, see Liquibase Database Tutorials.

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.

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

=[STRICT or LAX]
Configures how to handle unknown fields in changelog files. Possible values: STRICT which causes parsing to fail, and LAX which continues with the parsing. Default value is "strict" (new in 4.14.0)
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.
duplicateFileMode How to handle multiple files being found in the search path that have duplicate paths. Options are WARN (log warning and choose one at random) or ERROR (fail current operation).
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.
liquibase.hub.logLevel=<level>
and
liquibase.hub.log-level=<level>
Specifies the log level for filtering log messages to send to Liquibase Hub during operations.
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