Configuration

ClickHouse loads its configuration from XML or YAML files. Server config lives in /etc/clickhouse-server/config.xml (and config.d/); user config lives in /etc/clickhouse-server/users.xml (and users.d/); per-client config in ~/.clickhouse-client/config.xml.

Loaders

• src/Common/Config/ConfigProcessor.cpp — parses the main XML/YAML, merges include directives, applies XML pre-processor.
• src/Common/Config/ConfigReloader.cpp — watches files and re-applies on change (where supported).
• src/Common/Config/AbstractConfigurationComparison.cpp — diffing config trees.
• src/Core/Settings.cpp — query-level settings.
• src/Core/ServerSettings.cpp — server-level settings.
• src/Core/SettingsEnums.cpp, SettingsConstraints.cpp — enum types and constraints.

Server config

The big knobs:

Section	Purpose
<logger>	Where logs go, log level, rotation.
<listen_host>, <tcp_port>, <http_port>, <mysql_port>, <postgresql_port>, <grpc_port>, <arrowflight_port>, <interserver_http_port>	Network listeners. See Server protocols.
<openSSL>	Certificate paths, client/server contexts, ciphers.
<remote_servers>	Cluster topology. See Distributed queries.
<keeper_server> / <zookeeper>	Either embed Keeper, or point to an external ensemble. See Coordination.
<storage_configuration>	Disks and storage policies. See IO and disks.
<merge_tree>	Default MergeTreeSettings overrides.
<compression>	Per-pattern column-codec defaults. See Compression.
<encryption_codecs>	Keys for AES_* codecs.
<user_directories>	Where access entities live (XML, disk, replicated). See Access control.
<users_config>	Path to users.xml.
<default_profile> / <default_database>	Defaults for new users.
<query_log>, <query_thread_log>, <part_log>, <text_log>, <metric_log>, <trace_log>, <asynchronous_metric_log>, <asynchronous_insert_log>, <crash_log>, <session_log>, <error_log>, <filesystem_cache_log>, <backup_log>, <latency_log>, <query_views_log>, <query_metric_log>, <blob_storage_log>, <distributed_ddl_queue>	Per-system-table sinks.
<background_pool_size>, <background_schedule_pool_size>, <max_concurrent_queries>, <max_server_memory_usage>	Pool sizing.
<dictionaries_config>, <named_collections_storage>, <udf>, <custom_settings_prefixes>, <format_schema_path>	Pluggability.
<prometheus>, <asynchronous_metrics_update_period_s>	Telemetry.
<distributed_ddl>	Path in Keeper for ON CLUSTER queue.
<macros>	Per-replica substitutions used by ReplicatedMergeTree.
<remote_url_allow_hosts>, <url_object_storage_allow_hosts>	Allowlists for url(...) / s3(...) table functions.

Includes:

• incl="..." pulls a snippet from another file.
• Files in config.d/ are merged automatically.
• YAML is supported (config.yaml, users.yaml).

User config

users.xml (or users.d/):

• <users><user_name> — credentials, networks, default profile, default database, default roles.
• <profiles> — settings profiles (collections of settings + constraints).
• <quotas> — usage quotas (queries, errors, rows, bytes, time).
• <settings_profiles>.

The same entities can be created via SQL (CREATE USER, CREATE PROFILE, CREATE QUOTA); SQL-managed entities live in DiskAccessStorage or ReplicatedAccessStorage (see Access control).

Settings

SET and ?setting=value apply per-query / per-session settings. system.settings describes them all (~1500 settings). The big categories:

• Memory and concurrency — max_memory_usage, max_threads, max_block_size, max_insert_block_size, max_execution_time.
• Query plan toggles — allow_experimental_*, optimize_*, enable_optimize_*.
• Distributed reads — prefer_localhost_replica, parallel_distributed_insert_select, distributed_aggregation_memory_efficient, max_parallel_replicas.
• Async insert — async_insert*.
• Joins — join_algorithm, join_use_nulls, partial_merge_join_*, cross_to_inner_join_rewrite.
• MergeTree reads — merge_tree_min_rows_for_concurrent_read, merge_tree_max_rows_to_use_cache, force_index_by_date, force_primary_key.
• Format I/O — input_format_*, output_format_*.
• Network compression — network_compression_method, network_zstd_compression_level.

Constraints (<constraints> in profiles, or ALTER SETTINGS PROFILE ... ADD CONSTRAINT) restrict how a user can override settings.

Reload behaviour

Most changes to config.xml reload at runtime (SYSTEM RELOAD CONFIG). Some settings (port bindings, keeper_server.<...>, <zookeeper>) need a server restart. The reload is logged in system.text_log.

Client config

~/.clickhouse-client/config.xml:

• <host>, <port>, <user>, <password>, <database>.
• <connections> — multiple named hosts (clickhouse-client --connection name).
• <openSSL> — TLS overrides for the client.
• <query_id_format> — generation pattern for client-side query ids.
• <output_format> — default format.

Related pages

• Server protocols
• Access control
• IO and disks
• Coordination