Creating and configuring a liquibase.properties file

A liquibase.properties file is a text-based file that allows you to store properties that don't change often. You can typically use this file to specify your database connection information. Using the liquibase.properties file saves you time and potential typing errors by removing the need to enter these properties as command line arguments.

Creating the file

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

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

Properties

The most common properties that you might specify in the liquibase.properties are listed below. The best practice is to configure the liquibase.properties file to include your driver class path, URL, and user authentication information for the database you want to capture.

Any property that could be specified on the command line can also be specified in the properties file. If a property is specified in both the properties file and the command line, the command line value will override the value in the file.

Property Definition
changeLogFile Specifies the path to the changelog to execute.
driver Specifies the driver class name for your target database.
referenceUrl Specifies the source database for performing comparisons.
username Specifies the username for your target database.
password Specifies the password for your target database.
referenceDriver Specifies the driver class name for your source database.
url Specifies the database you want to use to compare to your source database. Also known as your target.
referenceUsername Specifies the username for your source database.
referencePassword Specifies the password for your source database.
liquibaseProLicenseKey Specifies your Liquibase Pro license key (If you have one).
classpath Specifies the directories and jar files to search for changelog files and custom extension classes. Multiple directories can be separated with ; on Windows or : on Linux or MacOS.

changeExecListenerClass

=<ChangeExecListener.ClassName>

Specifies the custom Change Exec Listener implementation to use.

changeExecListenerPropertiesFile

=</path/to/file.properties>

Specifies properties for Change Exec Listener.

changeSetAuthor

Specifies the author of auto-generated changesets.

changeSetContext

Specifies the execution context to be used for changesets in the generated changelog, which can be "," separated if there are multiple contexts.

contexts=<value>

Specifies changeset contexts to execute.

currentDateTimeFunction=<value>

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

databaseChangeLogLockTableName

=<name>

Specifies the Liquibase changelog lock table. Default: DATABASECHANGELOGLOCK.

databaseChangeLogTableName

=<name>

Specifies the Liquibase changelog table. Default: DATABASECHANGELOG.

databaseChangeLogTablespaceName

=<name>

Specifies the tablespace where the DATABASECHANGELOGLOCK and DATABASECHANGELOG tables will be created if they don't exist yet.

databaseClass =<custom.DatabaseImpl>

Specifies a custom database implementation to use.

dataOutputDirectory

Specifies the directory where insert statement csv files will be kept. Required by the generateChangeLog command.

defaultCatalogName

Specifies the default catalog name to use for the database connection.

defaultSchemaName

Specifies the default schema name to use for the database connection.

delimiter=<string>

Sets the string used to break up files that consist of multiple statements. Used with ExecuteSqlCommand.

diffTypes

Specifies the list of diff types to include in the changelog expressed as a comma-separated list from: tables, views, columns, indexes, foreignkeys, primarykeys, uniqueconstraints, data. If this is null, then the default types will be: tables, views, columns, indexes, foreignkeys, primarykeys, uniqueconstraints.

Note:The exact list of options depends on the version and plugins that you have installed. Liquibase Pro provides additional options as well.

driverPropertiesFile

Specifies the location of a JDBC connection properties file which contains properties that the driver will use.

excludeObjects

Specifies objects to be excluded from the changelog. The example of filters: "table_name", "table:main_.*", "column:*._lock, table:primary.*".

includeCatalog=<true or false>

Includes the catalog in the generated changesets.
if the value is set to true. Default value is: false.

includeObjects

Specifies objects to be included in the changelog. The example of filters: "table_name", "table:main_.*", "column:*._lock, table:primary.*".

includeSchema=<true or false>

Includes the schema in the generated changesets if the value is set to true. 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, if
the value is set to true. Default value is: false

labels=<value>

Filters the changelog using labels.

liquibaseCatalogName

Specifies the catalog name where the Liquibase tables will be located.

liquibaseHubApiKey

Specifies API key for authorization to Hub.

liquibaseHubUrl

Specifies URL to Hub.

liquibaseSchemaName

Specifies the schema name where the Liquibase tables will be located.

logFile=<filename>

Sends logging messages to a file.

logLevel=<level>

Specifies the execution log level (debug, info, warning, severe, off).

outputDefaultCatalog=<true or false>

Specifies the catalog name that the SQL object references will include, if the value is set to true, even if it is the default catalog.

outputDefaultSchema=<true or false>

Specifies the schema name that the SQL object references will include, if the value is set to true, even if it is the default schema.

outputFile=<file>

Specifies the file to write output for the commands that write it.

outputSchemasAs

Uses the names as schemaName instead of the real names on diffChangeLog and generateChangeLog commands.

overwriteOutputFile=true

Forces overwriting the generated changelog/SQL files.

parameter.*

Passes any property starting with parameter as a changelog parameter.

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

promptForNonLocalDatabase

=<true or false>

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

propertyProviderClass =<properties.ClassName>

Specifies custom properties implementation to
use.

referenceDefaultCatalogName

Specifies the reference database catalog to use.

referenceDefaultSchemaName

Specifies the reference database schema to use.

referenceSchemas=<name1,name2>

Specifies a comma-separated list of reference database schemas from which to include objects when executing a command, such as snapshot, generateChangeLog, or diffChangeLog. It is required when you are referencing multiple schemas in a command.

rollbackScript

Specifies the path to a rollback script. If you perform the rollback, the contents of this script will be used to do the rollback rather than what is included in 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, generateChangeLog, or diffChangeLog. It is required when you are referencing multiple schemas in a command.

snapshotFormat

Specifies the file format when you run the
snapshot or snapshotReference command.

sqlFile

Specifies the file where SQL statements are stored.

strict=<true|false>

Defines whether Liquibase will fail with a validation error if any unknown or inapplicable properties are specified in the liquibase.properties file. In this case, the value should be set to true.

Default value is: false.

Different commands require different property information to work. For more information on the property requirements, see Liquibase commands.

Note: For Liquibase Pro users, setting the liquibaseProLicenseKey removing the need to include the license key on every Liquibase command.

liquibase.properties file example

Depending on the database you use, the values of properties vary. For more information about the format of properties, see Liquibase Database Tutorials and select the database you are using.

In the following example, you can see the liquibase.properties file configured specifically for an Oracle database.

changeLogFile: ../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

Adding your Liquibase Pro license key

As you can see in the example above, to add your Liquibase Pro license key, just add the liquibaseProLicenseKey: attribute to your liquibase.properties file and add your license key. Then save your file.

Additional Liquibase properties

You can include the following properties in the liquibase.properties file as of Liquibase 4.1. If you use the previous Liquibase versions, set these properties as java system properties. For example, in the CLI, the properties can be set with JAVA_OPTS=-“Dliquibase.x=a -Dliquibase.y=b”.

Property Definition

liquibase.ignoreRecycleBinWarning=<false|fasle>

Doesn't 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: 5.

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/generateChangeLog 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 diffChangeLog and if the value if set to true. Default value is: false.

liquibase.pro.synonyms.drop.public

Doesn't drop public synonyms in diffChangeLog or dropAll 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