ClickHouse/docs/en/engines/database-engines/atomic.md

slug	sidebar_label	sidebar_position
/en/engines/database-engines/atomic	Atomic	10

Atomic

It supports non-blocking DROP TABLE and RENAME TABLE queries and atomic EXCHANGE TABLES queries. Atomic database engine is used by default. Note that on ClickHouse Cloud, the Replicated database engine is used by default.

Creating a Database

CREATE DATABASE test [ENGINE = Atomic];

Specifics and recommendations

Table UUID

All tables in database Atomic have persistent UUID and store data in directory /clickhouse_path/store/xxx/xxxyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy/, where xxxyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy is UUID of the table. Usually, the UUID is generated automatically, but the user can also explicitly specify the UUID in the same way when creating the table (this is not recommended).

For example:

CREATE TABLE name UUID '28f1c61c-2970-457a-bffe-454156ddcfef' (n UInt64) ENGINE = ...;

:::note You can use the show_table_uuid_in_table_create_query_if_not_nil setting to display the UUID with the SHOW CREATE query. :::

RENAME TABLE

RENAME queries are performed without changing the UUID or moving table data. These queries do not wait for the completion of queries using the table and are executed instantly.

DROP/DETACH TABLE

On DROP TABLE no data is removed, database Atomic just marks table as dropped by moving metadata to /clickhouse_path/metadata_dropped/ and notifies background thread. Delay before final table data deletion is specified by the database_atomic_delay_before_drop_table_sec setting. You can specify synchronous mode using SYNC modifier. Use the database_atomic_wait_for_drop_and_detach_synchronously setting to do this. In this case DROP waits for running SELECT, INSERT and other queries which are using the table to finish. Table will be actually removed when it's not in use.

EXCHANGE TABLES/DICTIONARIES

EXCHANGE query swaps tables or dictionaries atomically. For instance, instead of this non-atomic operation:

RENAME TABLE new_table TO tmp, old_table TO new_table, tmp TO old_table;

you can use one atomic query:

EXCHANGE TABLES new_table AND old_table;

ReplicatedMergeTree in Atomic Database

For ReplicatedMergeTree tables, it is recommended not to specify engine parameters - path in ZooKeeper and replica name. In this case, configuration parameters default_replica_path and default_replica_name will be used. If you want to specify engine parameters explicitly, it is recommended to use {uuid} macros. This is useful so that unique paths are automatically generated for each table in ZooKeeper.

See Also

• system.databases system table