cloneTable

cloneTable is a Change Type in the Liquibase Pro Databricks extension that clones a table. It is available in the Liquibase Pro Databricks extension 1.0.0 and later.

Uses

You can use this change to create a clone of an existing Databricks table without affecting the original. There are two types of clones:

  • Shallow clones: copies only the source table's metadata to the target table. Shallow clones display the data of the source table. This is useful if you want to create a quick copy of a table without duplicating any data. However, it creates a dependency between the source and target tables.
  • Deep clones: copies both the source table's metadata and row contents to the target table. This is useful if you want to create a fully independent copy of a table without any dependencies. However, it is an expensive operation.

For more information, see Databricks: Clone a table on Databricks and Databricks SQL Reference: CREATE TABLE CLONE.

Also, you can optionally clone a specific instance of the table using either its Databricks commit version or associated timestamp. For more information, see Work with Delta Lake table history.

Run cloneTable

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:
    4. liquibase update

Available attributes

Tip: You must specify all top-level attributes marked as required. If you specify an optional attribute, you must also specify any nested attributes that it requires.

Name Type Description Requirement
sourceTableName String Name of the table to clone (existing table name) Required
targetTableName String Name of the table to create (new table name) Required
asOfDate String

Whenever you modify your table, Databricks captures different states of the table in a "commit," which includes a timestamp. You can use this attribute to specify the timestamp representing the state of your table. For example, you can specify 2025-01-01 or 2022-08-02 00:00:00. For more information, see Work with Delta Lake table history.

 Optional
asOfVersion Integer

Whenever you modify your table, Databricks captures different states of the table in a "commit," which includes a version number. You can use this attribute to specify the version of your table. For example, you can specify 1 or 15. For more information, see Work with Delta Lake table history.

 Optional
cloneMode String

The type of clone to make. Valid values are: SHALLOW, DEEP. If you specify SHALLOW, Databricks copies the source table's definition, but references the source table's files. If you specify DEEP, Databricks makes a complete, independent copy of the source table. Default: DEEP.

 Optional
ifNotExists Boolean

If true, creates the object only if it does not already exist. Appends IF NOT EXISTS syntax to SQL query.

Optional
replaceIfExists Boolean

If true, Liquibase uses CREATE OR REPLACE syntax when creating the new table. Default: false.

 Optional
sourceCatalogName String

Name of the catalog containing the table to clone

 Optional
sourceSchemaName String

Name of the schema containing the table to clone

 Optional
tableLocation String

File path to the external directory to create the table in, such as an AWS S3 resource location.

 Optional
targetCatalogName String

Name of the catalog containing the table to create

 Optional
targetSchemaName String

Name of the schema containing the table to create

 Optional
tblProperties String

The table properties you want to specify. Specify properties using the format 'key'='value'. Separate multiple properties using commas.

 Optional

Examples

databaseChangeLog:
  - changeSet:
      id: 3
      author: your.name
      changes:
        - cloneTable:
            sourceTableName: cloneable_table
            targetTableName: default_shallow_clone
            ifNotExists: true
            cloneMode: SHALLOW
      rollback:
        - dropTable:
            tableName: default_shallow_clone
  - changeSet:
      id: 4
      author: your.name
      changes:
        - cloneTable:
            sourceTableName: cloneable_table
            targetTableName: default_deep_clone
            replaceIfExists: true
            tblProperties: "'my.key1'='value1','my.key2'='value2'"
            tableLocation: s3://your/path/to/directory
            asOfVersion: 1
      rollback:
        - dropTable:
            tableName: default_shallow_clone
{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "3",
        "author": "your.name",
        "changes": [
          {
            "cloneTable": {
              "sourceTableName": "cloneable_table",
              "targetTableName": "default_shallow_clone",
              "ifNotExists": true,
              "cloneMode": "SHALLOW"
            }
          }
        ],
        "rollback": [
          {
            "dropTable": {
              "tableName": "default_shallow_clone"
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "4",
        "author": "your.name",
        "changes": [
          {
            "cloneTable": {
              "sourceTableName": "cloneable_table",
              "targetTableName": "default_deep_clone",
              "replaceIfExists": true,
              "tblProperties": "'my.key1'='value1','my.key2'='value2'",
              "tableLocation": "s3://your/path/to/directory",
              "asOfVersion": "1"
            }
          }
        ],
        "rollback": [
          {
            "dropTable": {
              "tableName": "default_shallow_clone"
            }
          }
        ]
      }
    }
  ]
}
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:databricks="http://www.liquibase.org/xml/ns/databricks"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/databricks
        http://www.liquibase.org/xml/ns/databricks/liquibase-databricks-latest.xsd
        http://www.liquibase.org/xml/ns/pro
        http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">

    <changeSet id="3" author="your.name">
        <pro-databricks:cloneTable
            sourceTableName="cloneable_table"
            targetTableName="default_shallow_clone"
            ifNotExists="true"
            cloneMode="SHALLOW"/>

        <rollback>
            <dropTable tableName="default_shallow_clone"/>
        </rollback>
    </changeSet>

    <changeSet id="4" author="your.name">
        <pro-databricks:cloneTable
            sourceTableName="cloneable_table"
            targetTableName="default_deep_clone"
            replaceIfExists="true"
            tblProperties="'my.key1'='value1','my.key2'='value2'"
            tableLocation="s3://your/path/to/directory"
            asOfVersion="1"/>

        <rollback>
            <dropTable tableName="default_shallow_clone"/>
        </rollback>
    </changeSet>
</databaseChangeLog>

Database support

This Change Type is only supported for Databricks. It does not support auto rollback.

Related links