Creating and configuring a file

A 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 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 file, generate a new text file in your project Liquibase directory and name it

Note: The file can also be named something other than 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.


The most common properties that you might specify in the are listed below. The best practice is to configure the file to include your driver, class path, and URL.

Note: While Liquibase allows for user authentication information (username and password) to be stored in the file, it is recommended that user credentials are stored in a secure credential repository or entered in the CLI when running a command.

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.



Specifies the custom Change Exec Listener implementation to use.



Specifies properties for Change Exec Listener.


Specifies the author of auto-generated changesets.


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


Specifies changeset contexts to execute.


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



Specifies the Liquibase changelog lock table. Default: DATABASECHANGELOGLOCK.



Specifies the Liquibase changelog table. Default: DATABASECHANGELOG.



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.


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


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


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


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


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.


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


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.


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


Filters the changelog using labels.


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


Specifies API key for authorization to Hub.


Specifies URL to Hub.


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


Sends logging messages to a file.


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.


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


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


Forces overwriting the generated changelog/SQL files.


Passes any property starting with parameter as a changelog parameter.

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


=<true or false>

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

propertyProviderClass =<properties.ClassName>

Specifies custom properties implementation to


Specifies the reference database catalog to use.


Specifies the reference database schema to use.


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.


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.


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.


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


Specifies the file where SQL statements are stored.


Defines whether Liquibase will fail with a validation error if any unknown or inapplicable properties are specified in the 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. 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 file configured specifically for an Oracle database.

changeLogFile: ../path/to/file/dbchangelog.xml
driver: oracle.jdbc.OracleDriver
url: jdbc:oracle:thin:@
username: PRO
password: password
referenceDriver: oracle.jdbc.OracleDriver
referenceUrl: jdbc:oracle:thin:@
referencePassword: password
liquibaseProLicenseKey: aeioufakekey32aeioufakekey785463214
classpath: ../path/to/file/ojdbc6-

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 file and add your license key. Then save your file.

Additional Liquibase properties

You can include the following properties in the 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 environment variable.

Windows example: set JAVA_OPTS=-Dliquibase.x=a -Dliquibase.y=b && liquibase --changeLogFile=dbchangelog.sql update

Linux example: JAVA_OPTS="-Dliquibase.x=a -Dliquibase.y=b" liquibase --changeLogFile=dbchangelog.sql update

Property Definition


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.


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


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


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


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


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


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


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


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


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


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.


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


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


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


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

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

Doesn't drop public synonyms in diffChangeLog or dropAll if the value is set to false. Default value is: true.

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