分布式 PostgreSQL 集群(Citus)官方教程 - 遷移現有應用程序
將現有應用程序遷移到 Citus 有時需要調整 schema 和查詢以獲得最佳性能。 Citus 擴展了 PostgreSQL 的分布式功能，但它不是擴展所有工作負載的直接替代品。高性能 Citus 集群需要考慮數據模型、工具和所使用的 SQL 功能的選擇。
第一步是優化現有的數據庫模式，以便它可以在多臺計算機上高效工作。
- 確定分布策略
選擇分布鍵(distribution key)
識別表的類型
- 為遷移準備源表
添加分布鍵
回填新創建的列
接下來，更新應用程序代碼和查詢以處理 schema 更改。
- 準備申請 Citus
建立開發 Citus 集群
向查詢添加分布鍵
啟用安全連接
檢查跨節點流量
在開發環境中測試更改后，最后一步是將生產數據遷移到 Citus 集群并切換生產應用程序。我們有技術可以最大限度地減少此步驟的停機時間。
- 遷移生產數據
小型數據庫遷移
大數據庫遷移
確定分布策略
選擇分布鍵
遷移到 Citus 的第一步是確定合適的distribution key 并相應地規劃表分布。在多租戶應用程序中，這通常是租戶的內部標識符。我們通常將其稱為“租戶 ID(tenant ID)”。用例可能會有所不同，因此我們建議您在此步驟中進行徹底檢查。
如需指導，請閱讀以下部分：
- 確定應用程序類型
https://docs.citusdata.com/en/v10.2/develop/app_type.html#app-type
- 選擇分布列
https://docs.citusdata.com/en/v10.2/sharding/data_modeling.html#distributed-data-modeling
我們很樂意幫助您檢查您的環境，以確保選擇了理想的 distribution key。為此，我們通常會檢查 schema 布局、更大的表、長時間運行和/或有問題的查詢、標準用例等。
確定表的類型
一旦確定了 distribution key，請查看 schema 以確定如何處理每個表以及是否需要對表布局進行任何修改。我們通常建議使用電子表格進行跟蹤，并創建了您可以使用的模板。
- https://docs.google.com/spreadsheets/d/1jYlc22lHdP91pTrb6s35QfrN9nTE1BkVJnCSZeQ7ZmI/edit
表格通常屬于以下類別之一：
- 準備分發。 這些表已經包含 distribution key，并準備好分發。
- 需要回填。 這些表可以按所選 key 進行邏輯分布，但不包含直接引用它的列。稍后將修改這些表以添加該列。
- 參考表。 這些表通常很小，不包含 distribution key，通常由分布式表連接，和/或在租戶之間共享。這些表中的每一個的副本將在所有節點上維護。常見示例包括國家代碼查找、產品類別等。
- 本地表。 這些通常不連接到其他表，并且不包含 distribution key。它們僅在 coordinator 節點上維護。常見示例包括管理員用戶查找和其他實用程序表。
考慮一個類似于 Etsy 或 Shopify 的示例多租戶應用程序，其中每個租戶都是商店。這是簡化 schema 的一部分：
(帶下劃線的項目是主鍵，斜體項目是外鍵。)
在此示例中，商店是自然租戶。在這種情況下，租戶 ID 是 store_id。在集群中分布表之后，我們希望與同一存儲相關的行一起駐留在同一節點上。
為遷移準備源表
一旦確定了所需數據庫更改的范圍，下一個主要步驟就是修改應用程序現有數據庫的數據結構。首先，修改需要回填的表，為 distribution key 添加一列。
添加分布鍵
在我們的店面示例中，stores 和 products 表有一個 store_id 并準備好分布。規范化后，line_items 表缺少商店 ID。如果我們想通過 store_id 分布，表需要這個列。
-- denormalize line_items by including store_id
ALTER TABLE line_items ADD COLUMN store_id uuid;
請務必檢查所有表中的分布列是否具有相同的類型，例如：不要混合 int 和 bigint。列類型必須匹配以確保正確的數據托管。
回填新創建的列
更新 schema 后，在添加該列的表中回填 tenant_id 列的缺失值。在我們的示例中，line_items 需要 store_id 的值。
我們通過從帶有訂單的 join 查詢中獲取缺失值來回填表：
UPDATE line_items
SET store_id = orders.store_id
FROM line_items
INNER JOIN orders
WHERE line_items.order_id = orders.order_id;
一次執行整個表可能會導致數據庫負載過大并中斷其他查詢。相反，回填可以更慢地完成。一種方法是創建一個一次回填小批量的函數，然后使用 pg_cron 重復調用該函數。
- https://github.com/citusdata/pg_cron
-- the function to backfill up to one
-- thousand rows from line_items
CREATE FUNCTION backfill_batch()
RETURNS void LANGUAGE sql AS $$
WITH batch AS (
SELECT line_items_id, order_id
FROM line_items
WHERE store_id IS NULL
LIMIT 10000
FOR UPDATE
SKIP LOCKED
)
UPDATE line_items AS li
SET store_id = orders.store_id
FROM batch, orders
WHERE batch.line_item_id = li.line_item_id
AND batch.order_id = orders.order_id;
$$;
-- run the function every quarter hour
SELECT cron.schedule('*/15 * * * *', 'SELECT backfill_batch()');
-- ^^ note the return value of cron.schedule
回填完成后，可以禁用 cron job：
-- assuming 42 is the job id returned
-- from cron.schedule
SELECT cron.unschedule(42);
準備申請 Citus
建立開發 Citus 集群
在修改應用程序以使用 Citus 時，您需要一個數據庫來進行測試。按照說明設置您選擇的單節點 Citus。
- https://docs.citusdata.com/en/v10.2/installation/single_node.html#development
接下來從應用程序的原始數據庫中轉儲 schema 的副本，并在新的開發數據庫中恢復 schema。
# get schema from source db
pg_dump \
--format=plain \
--no-owner \
--schema-only \
--file=schema.sql \
--schema=target_schema \
postgres://user:pass@host:5432/db
# load schema into test db
psql postgres://user:pass@testhost:5432/db -f schema.sql
該 schema 應在您希望分發的所有表中包含一個分發鍵(tenant id)。在 pg_dumping schema 之前，請確保您已完成上一節中的準備源表以進行遷移的步驟。
在鍵中包含分布列
Citus 不能強制唯一性約束，除非唯一索引或主鍵包含分布列。因此，我們必須在示例中修改主鍵和外鍵以包含 store_id。
- https://docs.citusdata.com/en/v10.2/reference/common_errors.html#non-distribution-uniqueness
下一節中列出的一些庫能夠幫助遷移數據庫 schema 以將分布列包含在鍵中。然而，下面是一個底層 SQL 命令示例，用于在開發數據庫中組合簡單鍵：
BEGIN;
-- drop simple primary keys (cascades to foreign keys)
ALTER TABLE products DROP CONSTRAINT products_pkey CASCADE;
ALTER TABLE orders DROP CONSTRAINT orders_pkey CASCADE;
ALTER TABLE line_items DROP CONSTRAINT line_items_pkey CASCADE;
-- recreate primary keys to include would-be distribution column
ALTER TABLE products ADD PRIMARY KEY (store_id, product_id);
ALTER TABLE orders ADD PRIMARY KEY (store_id, order_id);
ALTER TABLE line_items ADD PRIMARY KEY (store_id, line_item_id);
-- recreate foreign keys to include would-be distribution column
ALTER TABLE line_items ADD CONSTRAINT line_items_store_fkey
FOREIGN KEY (store_id) REFERENCES stores (store_id);
ALTER TABLE line_items ADD CONSTRAINT line_items_product_fkey
FOREIGN KEY (store_id, product_id) REFERENCES products (store_id, product_id);
ALTER TABLE line_items ADD CONSTRAINT line_items_order_fkey
FOREIGN KEY (store_id, order_id) REFERENCES orders (store_id, order_id);
COMMIT;
至此完成，上一節中的 schema 將如下所示：
(帶下劃線的項目是主鍵，斜體項目是外鍵。)
請務必修改數據流以向傳入數據添加鍵。
向查詢添加分布鍵
一旦 distribution key 出現在所有適當的表上，應用程序就需要將它包含在查詢中。以下步驟應使用在開發環境中運行的應用程序副本完成，并針對 Citus 后端進行測試。在應用程序與 Citus 一起工作后，我們將了解如何將生產數據從源數據庫遷移到真正的 Citus 集群中。
- 應更新寫入表的應用程序代碼和任何其他攝取進程以包含新列。
- 在 Citus 上針對修改后的 schema 運行應用程序測試套件是確定哪些代碼區域需要修改的好方法。
- 啟用數據庫日志記錄是個好主意。這些日志可以幫助發現多租戶應用程序中的雜散跨分片查詢，這些查詢應轉換為每租戶查詢。
支持跨分片查詢，但在多租戶應用程序中，大多數查詢應針對單個節點。對于簡單的 select、update 和 delete 查詢，這意味著 where 子句應按 tenant id 進行過濾。Citus 然后可以在單個節點上有效地運行這些查詢。
許多流行的應用程序框架都有一些幫助程序庫，可以很容易地在查詢中包含租戶 ID：
- Ruby on Rails
https://docs.citusdata.com/en/v10.2/develop/migration_mt_ror.html
- Django
https://docs.citusdata.com/en/v10.2/develop/migration_mt_django.html
- ASP.NET
https://docs.citusdata.com/en/v10.2/develop/migration_mt_asp.html
- Java Hibernate
https://www.citusdata.com/blog/2018/02/13/using-hibernate-and-spring-to-build-multitenant-java-apps/
可以先將庫用于數據庫寫入(包括數據攝取)，然后再用于讀取查詢。例如，activerecord-multi-tenant gem 有一個只修改寫查詢的只寫模式(write-only mode)。
- activerecord-multi-tenant
https://github.com/citusdata/activerecord-multi-tenant
- write-only mode
https://github.com/citusdata/activerecord-multi-tenant#rolling-out-activerecord-multi-tenant-for-your-application-write-only-mode
其他(SQL原則)
如果您使用與上述不同的 ORM，或者更直接地在 SQL 中執行多租戶查詢，請遵循這些一般原則。我們將使用我們之前的電子商務應用程序示例。
假設我們想要獲取訂單的詳細信息。過濾租戶 ID 的分布式查詢在多租戶應用程序中運行效率最高，因此下面的更改使查詢更快(而兩個查詢返回相同的結果)：
-- before
SELECT *
FROM orders
WHERE order_id = 123;
-- after
SELECT *
FROM orders
WHERE order_id = 123
AND store_id = 42; -- <== added
租戶 id 列不僅對插入語句有益，而且至關重要。插入必須包含租戶 id 列的值，否則 Citus 將無法將數據路由到正確的分片并引發錯誤。
最后，在 join 表時，請確保也按租戶 ID 進行過濾。例如，這里是如何檢查給定商店已售出多少“很棒的羊毛褲”：
-- One way is to include store_id in the join and also
-- filter by it in one of the queries
SELECT sum(l.quantity)
FROM line_items l
INNER JOIN products p
ON l.product_id = p.product_id
AND l.store_id = p.store_id
WHERE p.name='Awesome Wool Pants'
AND l.store_id='8c69aa0d-3f13-4440-86ca-443566c1fc75'
-- Equivalently you omit store_id from the join condition
-- but filter both tables by it. This may be useful if
-- building the query in an ORM
SELECT sum(l.quantity)
FROM line_items l
INNER JOIN products p ON l.product_id = p.product_id
WHERE p.name='Awesome Wool Pants'
AND l.store_id='8c69aa0d-3f13-4440-86ca-443566c1fc75'
AND p.store_id='8c69aa0d-3f13-4440-86ca-443566c1fc75'
啟用安全連接
客戶端應使用 SSL 連接到 Citus 以保護信息并防止中間人攻擊。事實上，Citus Cloud 拒絕未加密的連接。要了解如何建立 SSL 連接，請參閱使用 SSL 連接。
- SSL 連接
https://docs.citusdata.com/en/v10.2/cloud/security.html#cloud-ssl
檢查跨節點流量
對于龐大而復雜的應用程序代碼庫，應用程序生成的某些查詢通常會被忽略，因此不會對它們使用 tenant_id 過濾器。Citus 的并行執行器仍然會成功執行這些查詢，因此，在測試期間，這些查詢仍然隱藏，因為應用程序仍然可以正常工作。但是，如果查詢不包含 tenant_id 過濾器，Citus 的執行程序將并行訪問每個分片，但只有一個會返回數據。這會不必要地消耗資源，并且只有在遷移到更高吞吐量的生產環境時才會出現問題。
為了防止在生產中啟動后才遇到此類問題，可以設置一個配置值來記錄命中多個分片的查詢。在正確配置和遷移的多租戶應用程序中，每個查詢一次只能命中一個分片。
在測試期間，可以配置以下內容：
-- adjust for your own database's name of course
ALTER DATABASE citus SET citus.multi_task_query_log_level = 'error';
如果 Citus 遇到將命中多個分片的查詢，它將出錯。測試期間出錯允許應用程序開發人員查找和遷移此類查詢。
在生產啟動期間，可以配置相同的設置來記錄，而不是錯誤輸出：
ALTER DATABASE citus SET citus.multi_task_query_log_level = 'log';
配置參數部分包含有關此設置支持的值的更多信息。
- 配置參數部分
https://docs.citusdata.com/en/v10.2/develop/api_guc.html#multi-task-logging
遷移生產數據
此時，已更新數據庫 schema 和應用程序查詢以與 Citus 一起使用，您已準備好進行最后一步。是時候將數據遷移到 Citus 集群并將應用程序切換到其新數據庫了。
數據遷移路徑取決于停機時間要求和數據大小，但通常屬于以下兩類之一。
- 小型數據庫遷移
- 大數據庫遷移
小型數據庫遷移
對于可以容忍一點停機時間的較小環境，請使用簡單的 pg_dump/pg_restore 進程。以下是步驟。
從您的開發數據庫中保存數據庫結構：
pg_dump \
--format=plain \
--no-owner \
--schema-only \
--file=schema.sql \
--schema=target_schema \
postgres://user:pass@host:5432/db
使用 psql 連接到 Citus 集群并創建 schema：
\i schema.sql運行您的 create_distributed_table 和 create_reference_table 語句。如果您收到有關外鍵的錯誤，通常是由于操作順序所致。在分發表之前刪除外鍵，然后重新添加它們。
將應用程序置于維護模式，并禁用對舊數據庫的任何其他寫入。
使用 pg_dump 將原始生產數據庫中的數據保存到磁盤：
pg_dump \
--format=custom \
--no-owner \
--data-only \
--file=data.dump \
--schema=target_schema \
postgres://user:pass@host:5432/db
使用 pg_restore 導入 Citus：
# remember to use connection details for Citus,
# not the source database
pg_restore \
--host=host \
--dbname=dbname \
--username=username \
data.dump
# it'll prompt you for the connection password
測試應用。
運行。
大數據庫遷移(Citus Cloud)
較大的環境可以使用 Citus Warp 進行在線復制。Citus Warp 允許您在更改發生時將更改從 PostgreSQL 源數據庫流式傳輸到 Citus Cloud 集群。就好像應用程序自動寫入兩個數據庫而不是一個，除非具有完美的事務邏輯。Citus Warp 可與啟用了 logical_decoding 插件的 Postgres 9.4 及更高版本一起使用(只要您使用的是 9.4 或更高版本，Amazon RDS 就支持此功能)。
對于此過程，我們強烈建議您通過開 ticket、聯系我們在 Slack 上的解決方案工程師之一或任何適合您的方法來聯系我們。為了進行 warp，我們通過 VPC 對等或 IP 白名單將 Citus 集群的 coordinator 節點連接到現有數據庫，并開始復制。
以下是開始 Citus Warp 流程之前需要執行的步驟：
- 在目標 Citus 集群上復制 schema 結構
- 在源數據庫中啟用邏輯復制
- 允許從 Citus coordinator 節點到源的網絡連接
- 聯系我們開始復制
重復 schema
將數據遷移到 Citus 的第一步是確保 schema 完全匹配，至少對于您選擇遷移的表而言。一種方法是針對您的開發數據庫(用于本地測試應用程序的 Citus 數據庫)運行 pg_dump --schema-only。在 coordinator Citus 節點上重放輸出。另一種方法是針對目標數據庫運行應用程序遷移腳本。
您希望遷移的所有表都必須具有主鍵。相應的目標表也必須具有主鍵，唯一的區別是這些鍵也允許組合以包含分布列，如識別分布策略中所述。
還要確保在開始復制之前在集群中分布表，這樣數據就不必單獨放在 coordinator 節點上。
啟用邏輯復制
某些托管數據庫(例如 Amazon RDS)需要通過更改服務器配置參數來啟用復制。在 RDS 上，您需要創建一個新參數組，在其中設置 rds.logical_replication = 1，然后將參數組設為活動參數組。應用更改需要重新啟動數據庫服務器，這可以安排在下一個維護時段。
如果您正在管理自己的 PostgreSQL 安裝，請將這些設置添加到 postgresql.conf：
wal_level = logical
max_replication_slots = 5 # has to be > 0
max_wal_senders = 5 # has to be > 0
需要重新啟動數據庫才能使更改生效。
開放訪問網絡連接
在 Cloud 控制臺中，確定主機名(以 db.citusdata.com 結尾)。Dig 主機名以找到其 IP 地址：
dig +short <hostname> A
如果您使用的是 RDS，請編輯入站數據庫安全組以添加自定義 TCP 規則：
Protocol
- TCP
Port Range
- 5432
Source
- /32
這會將 Citus coordinator 節點的 IP 地址列入白名單以進行入站連接。連接兩者的另一種方法是在它們的 VPC 之間建立對等互連。如果需要，我們可以幫助進行設置。
開始復制
通過在 Citus Cloud 控制臺中打開 support ticket 與我們聯系。云工程師將使用 Citus Warp 連接到您的數據庫，以執行初始數據庫轉儲、打開復制槽并開始復制。我們可以在遷移中包含/排除您選擇的表。
在復制的第一階段，如果數據庫處于寫入負載下，Postgres 預寫日志 (WAL) 可能會大幅增長。在開始此過程之前，請確保源數據庫上有足夠的磁盤空間。我們建議 100GB 可用空間或總磁盤空間的 20%，以較大者為準。一旦初始 dump/restore 完成并開始復制，那么數據庫將能夠再次歸檔未使用的 WAL 文件。
隨著 Warp 的進行，請注意源數據庫上的磁盤使用情況。如果源和目標之間存在數據類型不匹配，或其他意外的 schema 更改，則復制可能會停止。在長時間停頓期間，復制槽可以在源上無限增長，從而導致潛在的崩潰。
由于復制停滯的可能性，我們強烈建議在進行 Citus warp 時盡量減少 schema 更改。如果需要進行侵入式 schema 更改，您將需要停止 warp 并重試。
進行侵入式 schema 更改的步驟：
- 請求 Citus Cloud 工程師停止 warp。
- 更改源數據庫上的 schema。
- 更改目標數據庫上的 schema。
- 再次開始 warp。
切換到 Citus 并停止與舊數據庫的所有連接
當復制趕上源數據庫的當前狀態時，還有一件事要做。由于復制過程的性質，序列值不會在目標數據庫上正確更新。為了獲得正確的序列值，例如 id 列，您需要在打開對目標數據庫的寫入之前手動調整序列值。
一旦這一切完成，應用程序就可以連接到新數據庫了。我們不建議同時寫入源數據庫和目標數據庫。
當應用程序切換到新數據庫并且源數據庫上沒有發生進一步的更改時，請再次聯系我們以刪除復制槽。遷移完成。
