分散式 PostgreSQL 叢集(Citus)官方安裝指南

單節點 Citus

Docker (Mac 與 Linux)

Docker 映象僅用於開發/測試目的, 並且尚未準備好用於生產用途。

您可以使用一個命令在 Docker 中啟動 Citus：

# start the image
docker run -d --name citus -p 5432:5432 -e POSTGRES_PASSWORD=mypass \
           citusdata/citus:10.2

# verify it's running, and that Citus is installed:
psql -U postgres -h localhost -d postgres -c "SELECT * FROM citus_version();"

您應該會看到最新版本的 Citus。

叢集啟動並執行後，您可以訪問我們關於多租戶應用程式或實時分析的教程，在幾分鐘內開始使用 Citus。

• https://docs.citusdata.com/en/v10.2/get_started/tutorial_multi_tenant.html#multi-tenant-tutorial
• https://docs.citusdata.com/en/v10.2/get_started/tutorial_realtime_analytics.html#real-time-analytics-tutorial

如果您的機器上已經執行了 PostgreSQL，則在啟動 Docker 容器時可能會遇到此錯誤：

Error starting userland proxy:
Bind for 0.0.0.0:5432: unexpected error address already in use

這是因為 Citus 映象嘗試繫結到標準 PostgreSQL 埠 5432。要解決此問題，請使用 -p 選項選擇不同的埠。您還需要在下面的 psql 命令中使用新埠。

Ubuntu 或 Debian

本節介紹在您自己的 Linux 機器上使用 deb 包設定單節點 Citus 叢集所需的步驟。

1. 安裝 PostgreSQL 14 和 Citus 擴充套件

# Add Citus repository for package manager
curl https://install.citusdata.com/community/deb.sh | sudo bash

# install the server and initialize db
sudo apt-get -y install postgresql-14-citus-10.2

2.初始化叢集

讓我們在磁碟上建立一個新資料庫。為了方便使用 PostgreSQL Unix domain socket 連線，我們將使用 postgres 使用者。

# this user has access to sockets in /var/run/postgresql
sudo su - postgres

# include path to postgres binaries
export PATH=$PATH:/usr/lib/postgresql/14/bin

cd ~
mkdir citus
initdb -D citus

Citus 是一個 Postgres 擴充套件。要告訴 Postgres 使用這個擴充套件，你需要將它新增到一個名為 shared_preload_libraries 的配置變數中：

echo "shared_preload_libraries = 'citus'" >> citus/postgresql.conf

3.啟動資料庫伺服器

最後，我們將為新目錄啟動一個 PostgreSQL 例項：

pg_ctl -D citus -o "-p 9700" -l citus_logfile start

上面您將 Citus 新增到 shared_preload_libraries。這讓它可以連線到 Postgres 的一些深層部分，交換查詢計劃器(query planner)和執行器(executor)。在這裡，我們載入 Citus 面向使用者的一面（例如您將很快呼叫的函式）：

psql -p 9700 -c "CREATE EXTENSION citus;"

4. 驗證安裝是否成功

要驗證安裝是否成功，並且 Citus 已安裝：

psql -p 9700 -c "select citus_version();"

您應該看到 Citus 擴充套件的詳細資訊。

Fedora, CentOS, 或 Red Hat

本節介紹在您自己的 Linux 機器上使用 RPM 包設定單節點 Citus 叢集所需的步驟。

1. 安裝 PostgreSQL 14 和 Citus 擴充套件

# Add Citus repository for package manager
curl https://install.citusdata.com/community/rpm.sh | sudo bash

# install Citus extension
sudo yum install -y citus102_14

2.初始化叢集

讓我們在磁碟上建立一個新資料庫。為了方便使用 PostgreSQL Unix domain socket 連線，我們將使用 postgres 使用者。

# this user has access to sockets in /var/run/postgresql
sudo su - postgres

# include path to postgres binaries
export PATH=$PATH:/usr/pgsql-14/bin

cd ~
mkdir citus
initdb -D citus

Citus 是一個 Postgres 擴充套件。要告訴 Postgres 使用這個擴充套件，你需要將它新增到一個名為 shared_preload_libraries 的配置變數中：

echo "shared_preload_libraries = 'citus'" >> citus/postgresql.conf

3.啟動資料庫伺服器

最後，我們將為新目錄啟動一個 PostgreSQL 例項：

pg_ctl -D citus -o "-p 9700" -l citus_logfile start

上面您將 Citus 新增到 shared_preload_libraries。這讓它可以連線到 Postgres 的一些深層部分，交換查詢計劃器(query planner)和執行器(executor)。在這裡，我們載入 Citus 面向使用者的一面（例如您將很快呼叫的函式）：

psql -p 9700 -c "CREATE EXTENSION citus;"

4. 驗證安裝是否成功

要驗證安裝是否成功，並且 Citus 已安裝：

psql -p 9700 -c "select citus_version();"

您應該看到 Citus 擴充套件的詳細資訊。

在此步驟中，您已完成安裝過程並準備好使用 Citus 叢集。 為了幫助您入門，我們提供了一個教程，其中包含有關在幾分鐘內使用示例資料設定 Citus 叢集的說明。

多節點 Citus

Ubuntu 或 Debian

本節介紹使用 deb 包在您自己的 Linux 機器上設定多節點 Citus 叢集所需的步驟。

在所有節點上執行的步驟

1. 新增倉庫

# Add Citus repository for package manager
curl https://install.citusdata.com/community/deb.sh | sudo bash

2. 安裝 PostgreSQL + Citus 並初始化資料庫

# install the server and initialize db
sudo apt-get -y install postgresql-14-citus-10.2

# preload citus extension
sudo pg_conftool 14 main set shared_preload_libraries citus

這會在 /etc/postgresql/14/main 中安裝集中配置，並在 /var/lib/postgresql/14/main 中建立資料庫。

3. 配置連線和認證

在啟動資料庫之前，讓我們更改其訪問許可權。預設情況下，資料庫伺服器僅偵聽 localhost 上的客戶端。作為此步驟的一部分，我們指示它偵聽所有 IP 介面，然後配置客戶端身份驗證檔案以允許來自本地網路的所有傳入連線。

sudo pg_conftool 14 main set listen_addresses '*'

sudo vi /etc/postgresql/14/main/pg_hba.conf

# Allow unrestricted access to nodes in the local network. The following ranges
# correspond to 24, 20, and 16-bit blocks in Private IPv4 address spaces.
host    all             all             10.0.0.0/8              trust

# Also allow the host unrestricted access to connect to itself
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust

您的 DNS 設定可能不同。 此外，這些設定對於某些環境來說過於寬鬆，請參閱我們關於提高工作人員安全性的說明。 PostgreSQL 手冊解釋瞭如何使它們更具限制性。

4. 啟動資料庫伺服器，建立 Citus 擴充套件

# start the db server
sudo service postgresql restart
# and make it start automatically when computer does
sudo update-rc.d postgresql enable

您必須將 Citus 擴充套件新增到要在叢集中使用的每個資料庫。 以下示例將副檔名新增到名為 postgres 的預設資料庫中。

# add the citus extension
sudo -i -u postgres psql -c "CREATE EXTENSION citus;"

在 coordinator 節點上執行的步驟

下面列出的步驟必須僅在執行了前面提到的步驟之後在 coordinator 節點上執行。

1. 新增 worker 節點資訊

我們需要通知 coordinator 有關其 worker 的資訊。為了新增這些資訊，我們呼叫一個 UDF，它將節點資訊新增到 pg_dist_node 目錄表中。對於我們的示例，我們假設有兩個 worker（名為 worker-101，worker-102）。將 worker 的 DNS 名稱（或 IP 地址）和伺服器埠新增到表中。

sudo -i -u postgres psql -c "SELECT * from citus_add_node('worker-101', 5432);"
sudo -i -u postgres psql -c "SELECT * from citus_add_node('worker-102', 5432);"

2. 驗證安裝是否成功

為了驗證安裝是否成功，我們檢查 coordinator 節點是否選擇了所需的工作配置。 這個命令在 psql shell 中執行時應該輸出我們新增到上面 pg_dist_node 表中的 worker 節點。

sudo -i -u postgres psql -c "SELECT * FROM citus_get_active_worker_nodes();"

準備使用 Citus

在此步驟中，您已完成安裝過程並準備好使用 Citus 叢集。可以通過 postgres 使用者在 psql 中訪問新的 Citus 資料庫：

sudo -i -u postgres psql

Fedora、CentOS 或 Red Hat

本節介紹在您自己的 Linux 機器上使用 RPM 包設定多節點 Citus 叢集所需的步驟。

在所有節點上執行的步驟

1. 新增倉庫

# Add Citus repository for package manager
curl https://install.citusdata.com/community/rpm.sh | sudo bash

2. 安裝 PostgreSQL + Citus 並初始化資料庫

# install PostgreSQL with Citus extension
sudo yum install -y citus102_14
# initialize system database (using RHEL 6 vs 7 method as necessary)
sudo service postgresql-14 initdb || sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
# preload citus extension
echo "shared_preload_libraries = 'citus'" | sudo tee -a /var/lib/pgsql/14/data/postgresql.conf

PostgreSQL 在 /usr/pgsql-14/bin 中新增了特定於版本的二進位制檔案，但您通常只需要 psql，它的最新版本已新增到您的路徑中，並且可以使用 service 命令來管理伺服器本身。

3. 配置連線和認證

在啟動資料庫之前，讓我們更改其訪問許可權。預設情況下，資料庫伺服器僅偵聽 localhost 上的客戶端。 作為此步驟的一部分，我們指示它偵聽所有 IP 介面，然後配置客戶端身份驗證檔案以允許來自本地網路的所有傳入連線。

sudo vi /var/lib/pgsql/14/data/postgresql.conf

# Uncomment listen_addresses for the changes to take effect
listen_addresses = '*'

sudo vi /var/lib/pgsql/14/data/pg_hba.conf

# Allow unrestricted access to nodes in the local network. The following ranges
# correspond to 24, 20, and 16-bit blocks in Private IPv4 address spaces.
host    all             all             10.0.0.0/8              trust

# Also allow the host unrestricted access to connect to itself
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust

您的 DNS 設定可能不同。 此外，這些設定對於某些環境來說過於寬鬆，請參閱我們關於提高 Worker 安全性的說明。PostgreSQL 手冊解釋瞭如何使它們更具限制性。

• https://docs.citusdata.com/en/v10.2/admin_guide/cluster_management.html#worker-security

4. 啟動資料庫伺服器，建立 Citus 擴充套件

# start the db server
sudo service postgresql-14 restart
# and make it start automatically when computer does
sudo chkconfig postgresql-14 on

您必須將 Citus 擴充套件新增到要在叢集中使用的每個資料庫。 以下示例將副檔名新增到名為 postgres 的預設資料庫中。

sudo -i -u postgres psql -c "CREATE EXTENSION citus;"

在 coordinator 節點上執行的步驟

下面列出的步驟必須僅在執行了前面提到的步驟之後在 coordinator 節點上執行。

1. 新增 worker 節點資訊

我們需要通知 coordinator 有關其 worker 的資訊。為了新增這些資訊，我們呼叫一個 UDF，它將節點資訊新增到 pg_dist_node 目錄表中。對於我們的示例，我們假設有兩個 worker（名為 worker-101，worker-102）。將 worker 的 DNS 名稱（或 IP 地址）和伺服器埠新增到表中。

sudo -i -u postgres psql -c "SELECT * from citus_add_node('worker-101', 5432);"
sudo -i -u postgres psql -c "SELECT * from citus_add_node('worker-102', 5432);"

2. 驗證安裝是否成功

為了驗證安裝是否成功，我們檢查 coordinator 節點是否選擇了所需的工作配置。 這個命令在 psql shell 中執行時應該輸出我們新增到上面 pg_dist_node 表中的 worker 節點。

sudo -i -u postgres psql -c "SELECT * FROM citus_get_active_worker_nodes();"

準備使用 Citus

在此步驟中，您已完成安裝過程並準備好使用 Citus 叢集。可以通過 postgres 使用者在 psql 中訪問新的 Citus 資料庫：

sudo -i -u postgres psql

更多

• Django-Multitenant，分散式多租戶資料庫專案實戰(Python/Django+Postgres+Citus)
• 分散式 PostgreSQL 叢集(Citus)官方示例 - 時間序列資料