分布式 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
