Create and Configure a `liquibase.properties` File

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:

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.

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.

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:

Using a text editor, open the Liquibase properties file.
Add licenseKey: to the list of parameters.
Specify your license key as the value, as the previous example shows.
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.

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 secure credential repository or enter them in the CLI when you run a command.

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

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`	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
`referenceUrl`	Specifies the source database for performing comparisons. Optional
`referenceUsername`	Specifies the username for the source database. Optional
`referencePassword`	Specifies the password for the source database.
`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 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.
`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`	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`.

Create and Configure a liquibase.properties File