convert-data-types parameter

The convert-data-types parameter is a Boolean that allows Liquibase to convert data types such as int, bigint, timestamp, and clob to the standard data types. The default value of the parameter is true.

Liquibase handles differences in data types for the following reasons:

  • To help with database independence by allowing a single changeset to work across different database vendors, even though there are differences in their data type names
  • To help with the database specific rules by automatically using the correct data types

For example, most databases have a data type represented by a large text block called clob, text, varchar(max), or something else. With Liquibase, if you have the following changeset and run it against Oracle, it will create the column as clob instead of throwing an “unknown data type: text” error:

<addColumn tableName="test_table">
<column name="new_col" type="text"/>
</addColumn>

If you run the same changeset against SQL Server, it will create a varchar(max) data type because varchar(max) is the "large text block" data type in SQL Server. Though SQL Server has a text data type, it is deprecated, and the correct type to use is varchar(max). If you want to create the text type changeset as the actual text type, use --convert-data-types=false or specify the SQL directly.

The data types being converted are:

  • blob
  • byte-array
  • date
  • time
  • datetime
  • timestamp

Liquibase considers other data types as standard and passes them through without any conversion.

Uses

In Liquibase, you can use the convert-data-types parameter when you want your database objects to be of the standard data types. The conversion depends on the database type and version. For example, you can use the convert-data-types parameter:

PostgreSQL

  • To keep serial rather than converting it to int generated by identity
  • To keep bigserial rather than converting it to bigint generated by identity

SQL Server

  • To keep text rather than converting it to varchar(max)
  • To keep timestamp rather than converting it to datetime

Setting the convert-data-types parameter

You can set the convert-data-types parameter in one of the following ways:

convert-data-types as a Java system property

You can set the convert-data-types parameter as a Java system property by using the JAVA_OPTS Environment Variable.

The syntax for Mac/Linux:

JAVA_OPTS=-Dliquibase.convertDataTypes=<true|false>

The syntax for Windows, which requires the set command:

set JAVA_OPTS=-Dliquibase.convertDataTypes=<true|false>

convert-data-types in the liquibase.properties file:

You can set the convert-data-types parameter by adding the following to your liquibase.properties file:

liquibase.convertDataTypes: <true|false>

convert-data-types as a CLI global parameter

You can use convert-data-types as a global parameter in your command line with a Liquibase command, such as update:

liquibase --convert-data-types=<true|false> update --changelog-file=dbchangelog.xml

convert-data-types as an environment variable

If you use Liquibase Pro, you can set convert-data-types as an environment variable.

The syntax for Mac/Linux:

LIQUIBASE_CONVERT_DATA_TYPES=<true|false>

The syntax for Windows, which requires the set command:

set LIQUIBASE_CONVERT_DATA_TYPES=<true|false>

Note: The commands shown above only apply to the current shell. If you need to pass an environment variable to a child process without affecting the parent process, you can use the export command on Mac/Linux or the setx command on Windows.