前言

本章節中，我們將會展示ClickHouse資料庫的設定檔與一些設定的介紹。

設定檔案介紹

ClickHouse資料庫有多個設定檔案且支援多檔案設定管理。假設我們是以DEB或RPM等套件方式安裝的話，則下列有幾個重要的設定檔案：

• 主要的伺服器設定檔案在
  • /etc/clickhouse-server/config.xml或是/etc/clickhouse-server/config.yaml
  • 其他的設定檔案必須放置在/etc/clickhouse-server/config.d目錄中。
  • 要注意的是任意的設定檔案的格式必須是XML或YAML但是兩者檔案格式在同一個檔案上呈現是不支援的。
  • 舉例來說，我們可以有主要設定檔為config.xml與users.xml並以YAML檔案格式寫額外的檔案並放置在config.d與users.d的目錄中。

所有的XML檔案應該要有同樣的根元素（root element），通常是<clickhouse>。對於YAML檔案格式clickhouse:不應該出現在YAML檔案中，內建的解析器將會自動寫入這個。

覆寫設定

一些設定是指定在主要的設定檔案中，且這些設定可以在其他的設定檔案中進行設定與覆寫。

• 替代（replace）或是移除（remove）屬性的動作可以在設定檔案中的元素進行。
• 如果上述的動作都沒有選擇的話，則會將元素內容的以遞迴方式合併在一起，將重複的子（children）元素進行替換值的動作。
• 如果替代（replace）指定的話，將會替換掉指定的裡面所有的元素內容。
• 如果移除（remove）指定的話，將會移除元素內容。
• 我們也可以以已經定義的環境變數方式來宣告屬性，例如：from_env="VARIABLE_NAME"，相關範例如下：

<clickhouse>
    <macros>
        <replica from_env="REPLICA" />
        <layer from_env="LAYER" />
        <shard from_env="SHARD" />
    </macros>
</clickhouse>

使用者設定

config.xml檔案可以指定多個分開設定，包括使用者設定（settings）、profiles與配額（quotas），可以使用相對路徑方式定義使用者設定檔案路徑在users_config元素中。

預設來說，是users.xml定義使用者相關的設定，若users_config元素在config.xml檔案中沒有出現，則使用者的settings、profiles與quotas直接指定在config.xml檔案中。

使用者設定可以分開成多個檔案，這情形類似config.xml與config.d/的目錄關係，users.d是用來放置分開的使用者設定檔。

XML檔案格式範例

假設有一個使用者定義檔案叫做alce.xml，其存放在/etc/clickhouse-server/users.d/alice.xml路徑，內容如下：

<clickhouse>
    <users>
      <alice>
            <profile>analytics</profile>
            <networks>
                <ip>::/0</ip>
            </networks>
          <password_sha256_hex>...</password_sha256_hex>
          <quota>analytics</quota>
      </alice>
    </users>
</clickhouse>

其中，analytics的profile與quota需要事先定義好才可以使用，若沒有先定義的話，則該profile會找不到，相關的建立使用者範例如下：

我們在Ubuntu 18.04上透過DEB套件方式進行ClickHouse資料庫安裝為例進行下列的建立使用者的設定檔案操作，首先，先以vim文字編輯器或是其他編輯器建立一個XML檔案在/etc/clickhouse-server/users.d/alice.xml路徑底下，相關的編輯檔案指令與設定檔案內容如下：

$ sudo vim /etc/clickhouse-server/users.d/alice.xml

<clickhouse>
    <profiles>
        <alice>
            <max_memory_usage>10000000000</max_memory_usage>
            <load_balancing>random</load_balancing>
        </alice>

        <readonly>
            <readonly>1</readonly>
        </readonly>
    </profiles>
    <quotas>
        <alice>
            <interval>
                <duration>3600</duration>
                <queries>0</queries>
                <errors>0</errors>
                <result_rows>0</result_rows>
                <read_rows>0</read_rows>
                <execution_time>0</execution_time>
            </interval>
        </alice>
    </quotas>
    <users>
      <alice>
          <profile>alice</profile>
          <networks>
            <ip>::/0</ip>
          </networks>
          <password remove='1' />
          <password_sha256_hex>sha256_password_hex</password_sha256_hex>
          <quota>alice</quota>
      </alice>
    </users>
</clickhouse>

從上面的設定檔案中的quotas與profiles都是參考自/etc/clickhouse-server/users.xml，這是ClickHouse資料庫預設使用者的設定檔，其中密碼部分sha256_password_hex可以替換成自己雜湊過的密碼，若要拿到明文經過SHA-256雜湊演算法且是十六進位的雜湊字串，則我們可以使用Python程式語言達到，將下列的程式碼中的your_password替換即可，相關的程式碼與執行所輸出的訊息如下：

localadmin@clickhouse01:~$ python3
Python 3.6.9 (default, Jun 29 2022, 11:45:57)
[GCC 8.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import hashlib
>>> hashlib.sha256('your_password'.encode('utf-8')).hexdigest()
'4da3376323046a3bb6759f0a3f4ae7100a0567950c53ee42d2e19201baaa6dfc'
>>> import sys
>>> sys.exit()
localadmin@clickhouse01:~$

若是對於PHP開發者或是當前的作業系統已經有php指令的話，則可以使用下列的方式在Ubuntu 18.04上完成，一樣也是將your_password的部分替換掉自己的明文密碼即可，相關的指令使用與輸出的訊息如下：

localadmin@clickhouse02:~$ php -v
PHP 8.1.9 (cli) (built: Aug 15 2022 09:39:35) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.9, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.9, Copyright (c), by Zend Technologies
localadmin@clickhouse02:~$ php -r "echo hash('sha256', 'your_password'),PHP_EOL;"
4da3376323046a3bb6759f0a3f4ae7100a0567950c53ee42d2e19201baaa6dfc
localadmin@clickhouse02:~$

設定好上述的設定檔之後，使用下列指令將此設定檔案的擁有者改為clickhouse使用者，相關的指令如下：

$ sudo ls /etc/clickhouse-server/users.d/alice.xml -al
-rw-r--r-- 1 root root 978 Sep 28 12:15 /etc/clickhouse-server/users.d/alice.xml
$ sudo chown clickhouse:clickhouse /etc/clickhouse-server/users.d/alice.xml
$ sudo ls /etc/clickhouse-server/users.d/alice.xml -al
-rw-r--r-- 1 clickhouse clickhouse 978 Sep 28 12:17 /etc/clickhouse-server/users.d/alice.xml

設定好alice使用者的設定檔之後，接著可以使用下列的指令將ClickHouse資料庫系統背景服務進行重新啟動，相關的指令如下：

localadmin@clickhouse01:~$ sudo systemctl restart clickhouse-server.service
localadmin@clickhouse01:~$ sudo systemctl status clickhouse-server.service
● clickhouse-server.service - ClickHouse Server (analytic DBMS for big data)
   Loaded: loaded (/lib/systemd/system/clickhouse-server.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2022-09-28 12:26:03 CST; 2s ago
 Main PID: 22870 (clckhouse-watch)
    Tasks: 201 (limit: 4915)
   CGroup: /system.slice/clickhouse-server.service
           ├─22870 clickhouse-watchdog --config=/etc/clickhouse-server/config.xml --pid-file=/run/clickhouse-server/clickhouse-server.pid
           └─22882 /usr/bin/clickhouse-server --config=/etc/clickhouse-server/config.xml --pid-file=/run/clickhouse-server/clickhouse-server.pid

Sep 28 12:26:03 clickhouse01 systemd[1]: Started ClickHouse Server (analytic DBMS for big data).
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Processing configuration file '/etc/clickhouse-server/config.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Logging trace to /var/log/clickhouse-server/clickhouse-server.log
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Logging errors to /var/log/clickhouse-server/clickhouse-server.err.log
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Processing configuration file '/etc/clickhouse-server/config.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Saved preprocessed configuration to '/var/lib/clickhouse/preprocessed_configs/config.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Processing configuration file '/etc/clickhouse-server/users.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Merging configuration file '/etc/clickhouse-server/users.d/alice.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Merging configuration file '/etc/clickhouse-server/users.d/default-password.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Saved preprocessed configuration to '/var/lib/clickhouse/preprocessed_configs/users.xml'.
localadmin@clickhouse01:~$

到這裡我們就完成了新增alice使用者到這個ClickHouse資料庫了，接下來可以使用下列的指令來驗證，相關的指令使用與輸出的訊息如下：

localadmin@clickhouse01:~$ clickhouse-client --user alice --password
ClickHouse client version 22.8.5.29 (official build).
Password for user (alice):
Connecting to 140.92.141.16:9000 as user alice.
Connected to ClickHouse server version 22.8.5 revision 54460.

Warnings:
 * Table system.session_log is enabled. It's unreliable and may contain garbage. Do not use it for any kind of security monitoring.

clickhouse01 :)

YAML檔案格式範例

使用YAML的檔案格式我們可以參考此範例設定檔：config.yaml.example。

YAML與XML檔案格式在定義ClickHouse資料庫相關設定上有不同的地方，下列是以YAML檔案格式編輯設定檔的方式：

我們可以使用下列的方式寫一個成對的鍵-值組：

key: value

要建立一個節點，並包含其他的節點時，可以使用Map，相關的語法如下：

map_key:
  key1: val1
  key2: val2
  key3: val3

若要建立有順序的鍵，或是節點賦予給一個標籤時，則我們可以使用Sequence，相關的語法如下：

seq_key:
  - val1
  - val2
  - key1: val3
  - map:
      key2: val4
      key3: val5

若我們要設定屬性值給Sequence或Map節點時，我們需要使用@在鍵值當作前綴的字元，@這個是YAML語法標準規定的，相關的語法如下：

map:
  "@attr1": value1
  "@attr2": value2
  key: 123

上述的Map節點則會等價於下列的XML內容：

<map attr1="value1" attr2="value2">
    <key>123</key>
</map>

上述這個YAML語法我們也可以用在Sequence上，相關的語法如下：

seq:
  - "@attr1": value1
  - "@attr2": value2
  - 123
  - abc

上述的Sequence節點可以等價於下列的XML內容：

<seq attr1="value1" attr2="value2">123</seq>
<seq attr1="value1" attr2="value2">abc</seq>

對於每個設定檔，在啟動時，ClickHouse資料庫伺服器也會個別產生file-preprocessed.xml檔案，這些檔案包含了所有完整的替代與覆寫，即會將我們設定在下列的路徑：

• /etc/clickhouse-server/config.xml
• /etc/clickhouse-server/users.xml
• /etc/clickhouse-server/config.d
• /etc/clickhouse-server/users.d

上述的有關使用者設定的檔案會彙整到users.xml，伺服器設定檔案也會彙整到config.xml，啟動ClickHouse資料庫的時候都會個別合併分開的設定檔，相關的訊息可以透過下列指令得知：

localadmin@clickhouse01:~$ sudo systemctl status clickhouse-server.service
● clickhouse-server.service - ClickHouse Server (analytic DBMS for big data)
   Loaded: loaded (/lib/systemd/system/clickhouse-server.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2022-09-28 12:26:03 CST; 2h 14min ago
 Main PID: 22870 (clckhouse-watch)
    Tasks: 205 (limit: 4915)
   CGroup: /system.slice/clickhouse-server.service
           ├─22870 clickhouse-watchdog --config=/etc/clickhouse-server/config.xml --pid-file=/run/clickhouse-server/clickhouse-server.pid
           └─22882 /usr/bin/clickhouse-server --config=/etc/clickhouse-server/config.xml --pid-file=/run/clickhouse-server/clickhouse-server.pid

Sep 28 12:26:03 clickhouse01 systemd[1]: Started ClickHouse Server (analytic DBMS for big data).
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Processing configuration file '/etc/clickhouse-server/config.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Logging trace to /var/log/clickhouse-server/clickhouse-server.log
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Logging errors to /var/log/clickhouse-server/clickhouse-server.err.log
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Processing configuration file '/etc/clickhouse-server/config.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Saved preprocessed configuration to '/var/lib/clickhouse/preprocessed_configs/config.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Processing configuration file '/etc/clickhouse-server/users.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Merging configuration file '/etc/clickhouse-server/users.d/alice.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Merging configuration file '/etc/clickhouse-server/users.d/default-password.xml'.
Sep 28 12:26:03 clickhouse01 clickhouse-server[22870]: Saved preprocessed configuration to '/var/lib/clickhouse/preprocessed_configs/users.xml'.
localadmin@clickhouse01:~$

從上述查看clickhouse-server的背景服務狀態所輸出的訊息可以得知，會個別將/etc/clickhouse-server/config.xml、/etc/clickhouse-server/config.d、/etc/clickhouse-server/users.d與/etc/clickhouse-server/users.xml等檔案個別解析與合併，最後儲存成預先處理的設定檔案，分別儲存成下列的檔案：

• /var/lib/clickhouse/preprocessed_configs/users.xml
• /var/lib/clickhouse/preprocessed_configs/config.xml

設定可以有下列幾種方法可以進行設定，設定的優先權順序如下：

• 在資料庫客戶端連線中使用SET語句進行設定。
• 若在資料庫客戶端連線中，沒有使用上述的語句進行設定，則會使用設定在資料庫的設定檔案中定義的設定。

相關的設定注意事項如下：

• users.xml設定檔為伺服器設定檔案。
  • 相關的使用者設定是定義在<profiles>元素中。
• 若要在資料庫連線中進行設定，可以使用SET setting=value語句進行設定，若是使用HTTP協定來進行設定，則需要帶入session_id之參數。

客製化設定

我們可以透過下列的方法進行設定，相關的範例如下：

<custom_settings_prefixes>custom_</custom_settings_prefixes>

或者可以使用SET語句進行設定，相關的範例如下：

SET custom_a = 123;

若要查詢設定則下列的語法如下：

SELECT getSetting('custom_a');

或者可以使用SHOW SETTINGS並搭配LIKE語句進行查詢設定：

SHOW SETTINGS LIKE '%custom_a%';

伺服器設定

所有有關於在/etc/clickhouse-server/config.xml設定檔案的伺服器設定的設定值完整的下列的網址：

• https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings

結論

從本章節中我們可以得知ClickHouse資料庫設定檔的分類與運作設定的機制，還有設定檔的格式。

參考資料

• https://clickhouse.com/docs/en/operations/configuration-files