convert-data-types

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 convert-data-types in four ways:

  • In the Liquibase properties file
  • As a global parameter in the CLI
  • As a JVM system property
  • As an environment variable (Liquibase Pro)

Liquibase properties file parameter

In Liquibase 4.1+, add the following to Liquibase properties file:

liquibase.convertDataTypes: <true|false>

CLI global parameter

In your command line, use a global parameter with a single Liquibase command:

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

Java system property

In your command line, use the JAVA_OPTS Environment Variable to set a JVM system property:

Mac/Linux syntax:

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

Windows syntax:

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

Note: To use a Liquibase command alongside JAVA_OPTS, add && liquibase <command> to the end of your input.

Environment variable (Liquibase Pro)

In Liquibase Pro, set an environment variable:

Mac/Linux syntax:

LIQUIBASE_CONVERT_DATA_TYPES=<true|false>

Windows syntax:

set LIQUIBASE_CONVERT_DATA_TYPES=<true|false>

Note: These environment variable commands 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.