How to Rename a Table in ClickHouse

Galaxy Glossary

How do I rename a table in ClickHouse?

RENAME TABLE instantly changes the table name—or even moves it to another database—without copying data.

Welcome to the Galaxy, Guardian!
You'll be receiving a confirmation email

Follow us on twitter :)

Oops! Something went wrong while submitting the form.

Description

Example H2

Example H3

Why would I rename a ClickHouse table?

Renaming keeps naming conventions consistent, lets you reflect business changes, and helps you test new schemas without duplicating data. ClickHouse performs the change atomically, so queries observe either the old or new name—never an in-between state.

What is the RENAME TABLE syntax?

The command supports single or multiple renames in one statement. You can rename inside the same database or move a table between databases as long as the table engines match.

How do I rename within the same database?

RENAME TABLE ecommerce.Orders TO ecommerce.CustomerOrders;

This updates all metadata references immediately. Existing queries using ecommerce.Orders fail after the rename, so update application code at the same deploy step.

How do I move a table to another database?

RENAME TABLE staging.Products TO analytics.Products;

Both databases must reside on the same cluster, and the destination name must be free. Moving large tables is instant because ClickHouse only updates metadata.

Can I rename several tables at once?

RENAME TABLE ecommerce.Orders TO ecommerce.Orders_2023,
ecommerce.OrderItems TO ecommerce.OrderItems_2023;

The operation is transactional—either all names change, or none do—avoiding partial updates during migrations.

Best practices

Bundle renames with application code changes, document the migration in version control, and back up system.tables metadata before running bulk renames.

Common mistakes

Renaming across clusters or mismatched engines fails; use ATTACH + DETACH or CREATE TABLE AS instead.

Why How to Rename a Table in ClickHouse is important

How to Rename a Table in ClickHouse Example Usage


-- Rename Orders to CustomerOrders in the ecommerce DB
RENAME TABLE ecommerce.Orders TO ecommerce.CustomerOrders;

How to Rename a Table in ClickHouse Syntax


RENAME TABLE [IF EXISTS] <source_db>.<source_table> TO <target_db>.<target_table>[, ...];

-- Ecommerce examples
-- 1. Simple rename in place
RENAME TABLE ecommerce.Customers TO ecommerce.CustomerAccounts;

-- 2. Move table between databases
RENAME TABLE staging.OrderItems TO analytics.OrderItems;

-- 3. Multiple renames in one transaction
RENAME TABLE ecommerce.Orders      TO ecommerce.Orders_2023,
             ecommerce.OrderItems TO ecommerce.OrderItems_2023;

Common Mistakes

Omitting the target database: RENAME TABLE Orders TO CustomerOrders; fails because ClickHouse expects fully qualified names. Always specify <db>.<table>.
Renaming to an existing table: ClickHouse throws an error if the target name exists. Drop or rename the destination first, or choose a unique name.