distributed_ddl_* server settings - ClickHouse Documentation

These settings configure the ClickHouse server and are autogenerated from ClickHouse source.

distributed_ddl

Manage executing distributed ddl queries (CREATE, DROP, ALTER, RENAME) on cluster. Works only if ZooKeeper is enabled. The configurable settings within <distributed_ddl> include:

Setting	Description	Default Value
`cleanup_delay_period`	cleaning starts after new node event is received if the last cleaning wasn’t made sooner than `cleanup_delay_period` seconds ago.	`60` seconds
`max_tasks_in_queue`	the maximum number of tasks that can be in the queue.	`1,000`
`path`	the path in Keeper for the `task_queue` for DDL queries
`pool_size`	how many `ON CLUSTER` queries can be run simultaneously
`profile`	the profile used to execute the DDL queries
`task_max_lifetime`	delete node if its age is greater than this value.	`7 * 24 * 60 * 60` (a week in seconds)

Example

<distributed_ddl>
    <!-- Path in ZooKeeper to queue with DDL queries -->
    <path>/clickhouse/task_queue/ddl</path>

    <!-- Settings from this profile will be used to execute DDL queries -->
    <profile>default</profile>

    <!-- Controls how much ON CLUSTER queries can be run simultaneously. -->
    <pool_size>1</pool_size>

    <!--
         Cleanup settings (active tasks will not be removed)
    -->

    <!-- Controls task TTL (default 1 week) -->
    <task_max_lifetime>604800</task_max_lifetime>

    <!-- Controls how often cleanup should be performed (in seconds) -->
    <cleanup_delay_period>60</cleanup_delay_period>

    <!-- Controls how many tasks could be in the queue -->
    <max_tasks_in_queue>1000</max_tasks_in_queue>
</distributed_ddl>

distributed_ddl_use_initial_user_and_roles

If enabled, ON CLUSTER queries will preserve and use the initiator’s user and roles for execution on remote shards. This ensures consistent access control across the cluster but requires that the user and roles exist on all nodes.

Last modified on July 23, 2026