Create and Configure a liquibase.properties File

You can use a defaults file called liquibase.properties to store information that Liquibase needs to connect to a particular database, along with other properties that rarely change. This lets you avoid entering properties through your command line, saving you time and reducing errors.

Arguments that are entered at a command prompt override values that are specified in liquibase.properties.

Creating a liquibase.properties file

Liquibase comes preinstalled with example liquibase.properties files in the $LIQUIBASE_HOME/examples/<sql|xml|yaml|json> directories. By default, when you run a command, Liquibase looks for the liquibase.properties file in the directory Liquibase is running in.

There are three ways to create a defaults file:

  • You can automatically generate a liquibase.properties file by running the init project command to create a new Liquibase project.
  • You can also manually create a new text file in your project Liquibase directory and name it liquibase.properties.
  • You can specify a custom name and location for your defaults file by using the --defaults-file parameter. For more information, see Working with Command Parameters.

Example defaults file

The following example liquibase.properties file works for an Oracle database:

changelogFile: ../path/to/file/dbchangelog.xml
driver: oracle.jdbc.OracleDriver
url: jdbc:oracle:thin:@192.168.0.22:1521/orcl
referenceDriver: oracle.jdbc.OracleDriver
referenceUrl: jdbc:oracle:thin:@192.168.0.22:1521/orcl
licenseKey: aeioufakekey32aeioufakekey785463214
classpath: ../path/to/file/ojdbc6-11.2.0.3.0.jar

This example does not include authentication properties such as username, password, referenceUsername, and referencePassword. It is a best practice to include sensitive credentials in a Secrets Management tool like AWS Secrets Manager or HashiCorp Vault. These tools require a Liquibase Pro license key.

Tip: 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.

Note: The Liquibase properties file does not support quoted property values, such as driver: "oracle.jdbc.OracleDriver". However, you can use quoted and unquoted values in the CLI.

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 licenseKey: to the list of parameters.
  3. Specify your license key as the value, as the previous example shows.
  4. Save the properties file.

See How to Apply Your Liquibase Pro License Key for more information.

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.

Warning: For security reasons, Liquibase strongly recommends that you do not include authentication information in your liquibase.properties file, such as the username, password, referenceUsername, and referencePassword properties. Instead, store them in a Secrets Management application or enter them in the CLI when you run a command.

The following table identifies some additional properties that can be specified in the liquibase.properties file. For a full list, see Liquibase Parameters.

Property Definition
changelogFile Specifies the path to the changelog to execute.
driver

Specifies the driver class name for the target database.
url Specifies the database to use when making comparisons to the source database. Also known as the target.
username

Username to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.
password

Password to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.
referenceDriver

Specifies the driver class name for the source database.

Optional

referenceUrl

Specifies the source database for performing comparisons.

Optional

referenceUsername

Specifies the username for the source database.

Optional

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.
referencePassword

Specifies the password for the source database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.
licenseKey Specifies the Liquibase Pro license key, if applicable. When added to the Liquibase properties file, licenseKey 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 the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets are executed in any particular migration run.

Note: If you use Liquibase 4.23.0 or earlier, use the syntax --contexts instead of --context-filter.
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 types of objects to compare. Specify multiple values as a comma-separated list (without spaces). Valid values are: catalogs, checkconstraints, columns, data, databasepackage, databasepackagebody, foreignkeys, functions, indexes, primarykeys, sequences, storedprocedures, tables, triggers, uniqueconstraints, views.

If null, default types are columns, foreignkeys, indexes, primarykeys, tables, uniqueconstraints, views.

Note: The diff types checkconstraints, databasepackage, databasepackagebody, functions, storedprocedures, and triggers require a valid Liquibase Pro license key to use.

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.
labelFilter=<value>

Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changesets will be executed in any migration run.
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.
liquibaseSchemaName

Specifies the schema name in which the Liquibase tables are located.
logFile=<filename> Sends logging messages to a file.
logLevel=<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.
outputFile=<file> Specifies the target file for command-written output.
outputSchemas

Lets you replace the schemas in the output changelog. This is a CSV list. The parameter size must match --schemas. If you have three items names in --schemas, you must also have three items in --output-schemas.

Example: liquibase generate-changelog --schemas=a,b,c --output-schemas=d,e,f

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.
preserveSchemaCase
=<true or false> 		Defines whether or not the casing in Schema Name is preserved. The default is false. When set to true, all Schema Names will preserve casing during update and rollback commands. This allows users to have a mixedCase schema name.

For example, if a case-sensitive database has a schema titled MySchema, Liquibase will attempt to update or rollback objects in MYSCHEMA until preserveSchemaCase is set to true.

This property is available in v4.12 and later. Using Liquibase with Snowflake and a mixed-case schema, you must configure defaultSchemaName="YourMixedCaseSchemaName" in the liquibase.properties file to use preserveSchemaCasing.
promptForNonLocalDatabase

=<true or false> 		Prompts if non-localhost databases are detected. Default value is false.
propertyProviderClass=<properties.ClassName> Specifies the custom properties implementation.
referenceDefaultCatalogName

The reference default catalog name to use for the database connection
referenceDefaultSchemaName

The reference default schema name to use for the database connection
referenceSchemas=<name1,name2>

Schemas names on reference database to use in diff. This is a CSV list.

Required when referencing multiple schemas in a command.
rollbackScript

The path to the script to use to perform the rollback. Only needed if the rollback is not already defined in the changelog, and if it is not a rollback statement that is automatically generated by Liquibase.
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

Output format to use. Creates a file of the specified type that represents the current state of the database. Valid values: JSON, YAML, TXT. Default: TXT.

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

Specifies the file where 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 update --changelog-file=dbchangelog.sql
  • Linux: JAVA_OPTS="-Dliquibase.x=a -Dliquibase.y=b" liquibase update --changelog-file=dbchangelog.sql
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.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