loadUpdateData

Loads or updates data from a CSV file into an existing table. It differs from loadData by issuing an SQL batch that checks for the existence of a record. If found, the record is UPDATEd, else the record is INSERTed. Also, generates DELETE statements for a rollback.

A value of NULL in a cell will be converted to a database NULL rather than the string NULL.

Uses

You can use loadUpdateData to update an existing CSV with new data. For example, consider a CSV called users.csv:

id,name 0,samantha 1,john 2,zelda

Imagine that you use loadData to insert these records into a table in your database whose primary key is id. Then imagine that the user John wants to go by Johnny instead, and you also get a new user named Tamanend. You can represent this in your CSV:

id,name 0,samantha 1,johnny 2,zelda 3,tamanend

Then use loadUpdateData to deploy the change to your database. Specify your CSV file, the name of the table to update, and the primary key of the table. For each row, Liquibase uses the primary key to determine whether the record exists:

  • If the record exists, Liquibase checks whether the database matches the CSV, and alters the table with the value in the CSV if needed. In this case, Liquibase replaces john with johnny.

  • If the record doesn't exist, Liquibase inserts it as a new row in the table. In this case, Liquibase adds a new row for tamanend.

Run loadUpdateData

To run this Change Type, follow these steps:

  1. Add the Change Type to your changeset, as shown in the examples on this page.

  2. Specify any required attributes. Use the table on this page to see which ones your database requires.

  3. Deploy your changeset by running the update command:liquibase update

Available attributes

Name

Description

Required for

Supports

Since

catalogName

Name of the catalog

all

3.0

commentLineStartsWith

Lines starting with this are treated as comments and ignored.

all

encoding

Encoding of the CSV file (defaults to UTF-8)

all

file

CSV file to load

all

all

onlyUpdate

If true, records with no matching database record should be ignored

all

3.3

primaryKey

A list of columns representing the primary key of the table (can be composite). Separate multiple values with commas. Liquibase uses the primary key column(s) to determine which columns need records to be inserted or updated. You must specify columns that exist in your CSV.

all

all

quotchar

The quote character for string fields containing the separator character.

all

relativeToChangelogFile

Specifies whether the file path is relative to the changelog file rather than looked up in the search path. Default: false.

all

schemaName

Name of the schema

all

separator

Character separating the fields.

all

tableName

Name of the table to insert or update data in

all

all

usePreparedStatements

Use prepared statements instead of insert statement strings if the database supports it.

all

Nested tags

Name

Description

Required for

Supports

Multiple allowed

column

Column mapping and defaults can be defined. The header or index attributes need to be defined. If the header name in the CSV is different than the column, name needs to be inserted. If no column is defined at all, the type is taken from a database. Otherwise, for non-string columns the type definition might be required.

Note: YAML and JSON changelogs using the column tag must nest it within a columns tag.

all

yes

Nested property attributes

Name

Description

name

Name of the column (Required).

header

Name of the column in the CSV file from which the value for the column will be taken if it's different from the column name. Ignored if index is also defined.

index

Index of the column in the CSV file from which the value for the column will be taken.

nullPlaceholder

Liquibase 4.31.0+. Specifies a placeholder string for Liquibase to search for in a loadData CSV file. If the CSV contains the value you specified for nullPlaceholder, Liquibase replaces that value with a NULL SQL reference.

type

Data type of the column. Its value has to be one of the accepted values of LOAD_DATA_TYPE. If you want to skip loading a specific column, use the skip data type described earlier. Otherwise, all columns in the CSV file will be used.

Database support

Database

Notes

Auto Rollback

DB2/LUW

Supported

No

DB2/z

Supported

No

Derby

Supported

No

Firebird

Supported

No

Google BigQuery

Supported

No

H2

Supported

No

HyperSQL

Supported

No

INGRES

Supported

No

Informix

Supported

No

MariaDB

Supported

No

MySQL

Supported

No

Oracle

Supported

No

PostgreSQL

Supported

No

Snowflake

Supported

No

SQL Server

Supported

No

SQLite

Supported

No

Sybase

Supported

No

Sybase Anywhere

Supported

No

Troubleshooting

CLOB data type handling

In Liquibase 4.29.2 and earlier, all CSV entries in a clob type column are assumed to be a path to a file. If Liquibase finds that file, it inserts the contents of the file into the table you're updating. If not, the execution stops with an error:

Caused by: java.io.FileNotFoundException: The file ExampleFileName was not found in the configured search path:

In Liquibase 4.30.0 and later, all CSV entries in a clob type column are assumed to be a path to a file by default. If Liquibase finds that file, it inserts the contents of the file into the table you're updating. If not, Liquibase inserts the string value as-is.

loadUpdateData examples

databaseChangeLog:
  - changeSet:
      id: loadUpdateData-example
      author: liquibase-docs
      changes:
        - loadUpdateData:
            catalogName: cat
            columns:
              - column:
                  header: header1
                  name: id
                  type: NUMERIC
              - column:
                  index: 3
                  name: name
                  type: BOOLEAN
            commentLineStartsWith: //
            encoding: UTF-8
            file: example/users.csv
            onlyUpdate: true
            primaryKey: pk_id
            quotchar: ''''
            relativeToChangelogFile: true
            schemaName: public
            separator: ;
            tableName: person
            usePreparedStatements: true

loadUpdateData - Liquibase