將現(xiàn)有應用程序遷移到 Citus 有時需要調(diào)整 schema 和查詢以獲得最佳性能。 Citus 擴展了 PostgreSQL 的分布式功能，但它不是擴展所有工作負載的直接替代品。高性能 Citus 集群需要考慮數(shù)據(jù)模型、工具和所使用的 SQL 功能的選擇。

第一步是優(yōu)化現(xiàn)有的數(shù)據(jù)庫模式，以便它可以在多臺計算機上高效工作。

• 確定分布策略

選擇分布鍵(distribution key)

識別表的類型

• 為遷移準備源表

添加分布鍵

回填新創(chuàng)建的列

接下來，更新應用程序代碼和查詢以處理 schema 更改。

• 準備申請 Citus

建立開發(fā) Citus 集群

向查詢添加分布鍵

啟用安全連接

檢查跨節(jié)點流量

在開發(fā)環(huán)境中測試更改后，最后一步是將生產(chǎn)數(shù)據(jù)遷移到 Citus 集群并切換生產(chǎn)應用程序。我們有技術(shù)可以最大限度地減少此步驟的停機時間。

• 遷移生產(chǎn)數(shù)據(jù)

小型數(shù)據(jù)庫遷移

大數(shù)據(jù)庫遷移

確定分布策略

選擇分布鍵

遷移到 Citus 的第一步是確定合適的distribution key 并相應地規(guī)劃表分布。在多租戶應用程序中，這通常是租戶的內(nèi)部標識符。我們通常將其稱為“租戶 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

我們很樂意幫助您檢查您的環(huán)境，以確保選擇了理想的 distribution key。為此，我們通常會檢查 schema 布局、更大的表、長時間運行和/或有問題的查詢、標準用例等。

確定表的類型

一旦確定了 distribution key，請查看 schema 以確定如何處理每個表以及是否需要對表布局進行任何修改。我們通常建議使用電子表格進行跟蹤，并創(chuàng)建了您可以使用的模板。

• https://docs.google.com/spreadsheets/d/1jYlc22lHdP91pTrb6s35QfrN9nTE1BkVJnCSZeQ7ZmI/edit

表格通常屬于以下類別之一：

• 準備分發(fā)。 這些表已經(jīng)包含 distribution key，并準備好分發(fā)。
• 需要回填。 這些表可以按所選 key 進行邏輯分布，但不包含直接引用它的列。稍后將修改這些表以添加該列。
• 參考表。 這些表通常很小，不包含 distribution key，通常由分布式表連接，和/或在租戶之間共享。這些表中的每一個的副本將在所有節(jié)點上維護。常見示例包括國家代碼查找、產(chǎn)品類別等。
• 本地表。 這些通常不連接到其他表，并且不包含 distribution key。它們僅在 coordinator 節(jié)點上維護。常見示例包括管理員用戶查找和其他實用程序表。

考慮一個類似于 Etsy 或 Shopify 的示例多租戶應用程序，其中每個租戶都是商店。這是簡化 schema 的一部分：

(帶下劃線的項目是主鍵，斜體項目是外鍵。)

在此示例中，商店是自然租戶。在這種情況下，租戶 ID 是 store_id。在集群中分布表之后，我們希望與同一存儲相關(guān)的行一起駐留在同一節(jié)點上。

為遷移準備源表

一旦確定了所需數(shù)據(jù)庫更改的范圍，下一個主要步驟就是修改應用程序現(xiàn)有數(shù)據(jù)庫的數(shù)據(jù)結(jié)構(gòu)。首先，修改需要回填的表，為 distribution key 添加一列。

添加分布鍵

在我們的店面示例中，stores 和 products 表有一個 store_id 并準備好分布。規(guī)范化后，line_items 表缺少商店 ID。如果我們想通過 store_id 分布，表需要這個列。

-- denormalize line_items by including store_id

ALTER TABLE line_items ADD COLUMN store_id uuid;

請務必檢查所有表中的分布列是否具有相同的類型，例如：不要混合 int 和 bigint。列類型必須匹配以確保正確的數(shù)據(jù)托管。

回填新創(chuàng)建的列

更新 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;

一次執(zhí)行整個表可能會導致數(shù)據(jù)庫負載過大并中斷其他查詢。相反，回填可以更慢地完成。一種方法是創(chuàng)建一個一次回填小批量的函數(shù)，然后使用 pg_cron 重復調(diào)用該函數(shù)。

• 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

建立開發(fā) Citus 集群

在修改應用程序以使用 Citus 時，您需要一個數(shù)據(jù)庫來進行測試。按照說明設(shè)置您選擇的單節(jié)點 Citus。

• https://docs.citusdata.com/en/v10.2/installation/single_node.html#development

接下來從應用程序的原始數(shù)據(jù)庫中轉(zhuǎn)儲 schema 的副本，并在新的開發(fā)數(shù)據(jù)庫中恢復 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 應在您希望分發(fā)的所有表中包含一個分發(fā)鍵(tenant id)。在 pg_dumping schema 之前，請確保您已完成上一節(jié)中的準備源表以進行遷移的步驟。

在鍵中包含分布列

Citus 不能強制唯一性約束，除非唯一索引或主鍵包含分布列。因此，我們必須在示例中修改主鍵和外鍵以包含 store_id。

• https://docs.citusdata.com/en/v10.2/reference/common_errors.html#non-distribution-uniqueness

下一節(jié)中列出的一些庫能夠幫助遷移數(shù)據(jù)庫 schema 以將分布列包含在鍵中。然而，下面是一個底層 SQL 命令示例，用于在開發(fā)數(shù)據(jù)庫中組合簡單鍵：

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;

至此完成，上一節(jié)中的 schema 將如下所示：

(帶下劃線的項目是主鍵，斜體項目是外鍵。)

請務必修改數(shù)據(jù)流以向傳入數(shù)據(jù)添加鍵。

向查詢添加分布鍵

一旦 distribution key 出現(xiàn)在所有適當?shù)谋砩?，應用程序就需要將它包含在查詢中。以下步驟應使用在開發(fā)環(huán)境中運行的應用程序副本完成，并針對 Citus 后端進行測試。在應用程序與 Citus 一起工作后，我們將了解如何將生產(chǎn)數(shù)據(jù)從源數(shù)據(jù)庫遷移到真正的 Citus 集群中。

• 應更新寫入表的應用程序代碼和任何其他攝取進程以包含新列。
• 在 Citus 上針對修改后的 schema 運行應用程序測試套件是確定哪些代碼區(qū)域需要修改的好方法。
• 啟用數(shù)據(jù)庫日志記錄是個好主意。這些日志可以幫助發(fā)現(xiàn)多租戶應用程序中的雜散跨分片查詢，這些查詢應轉(zhuǎn)換為每租戶查詢。

支持跨分片查詢，但在多租戶應用程序中，大多數(shù)查詢應針對單個節(jié)點。對于簡單的 select、update 和 delete 查詢，這意味著 where 子句應按 tenant id 進行過濾。Citus 然后可以在單個節(jié)點上有效地運行這些查詢。

許多流行的應用程序框架都有一些幫助程序庫，可以很容易地在查詢中包含租戶 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/

可以先將庫用于數(shù)據(jù)庫寫入(包括數(shù)據(jù)攝取)，然后再用于讀取查詢。例如，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 中執(zhí)行多租戶查詢，請遵循這些一般原則。我們將使用我們之前的電子商務應用程序示例。

假設(shè)我們想要獲取訂單的詳細信息。過濾租戶 ID 的分布式查詢在多租戶應用程序中運行效率最高，因此下面的更改使查詢更快(而兩個查詢返回相同的結(jié)果)：

-- before
SELECT *
  FROM orders
 WHERE order_id = 123;

-- after
SELECT *
  FROM orders
 WHERE order_id = 123
   AND store_id = 42; -- <== added

租戶 id 列不僅對插入語句有益，而且至關(guān)重要。插入必須包含租戶 id 列的值，否則 Citus 將無法將數(shù)據(jù)路由到正確的分片并引發(fā)錯誤。

最后，在 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

檢查跨節(jié)點流量

對于龐大而復雜的應用程序代碼庫，應用程序生成的某些查詢通常會被忽略，因此不會對它們使用 tenant_id 過濾器。Citus 的并行執(zhí)行器仍然會成功執(zhí)行這些查詢，因此，在測試期間，這些查詢?nèi)匀浑[藏，因為應用程序仍然可以正常工作。但是，如果查詢不包含 tenant_id 過濾器，Citus 的執(zhí)行程序?qū)⒉⑿性L問每個分片，但只有一個會返回數(shù)據(jù)。這會不必要地消耗資源，并且只有在遷移到更高吞吐量的生產(chǎn)環(huán)境時才會出現(xiàn)問題。

為了防止在生產(chǎn)中啟動后才遇到此類問題，可以設(shè)置一個配置值來記錄命中多個分片的查詢。在正確配置和遷移的多租戶應用程序中，每個查詢一次只能命中一個分片。

在測試期間，可以配置以下內(nèi)容：

-- adjust for your own database's name of course

ALTER DATABASE citus SET citus.multi_task_query_log_level = 'error';

如果 Citus 遇到將命中多個分片的查詢，它將出錯。測試期間出錯允許應用程序開發(fā)人員查找和遷移此類查詢。

在生產(chǎn)啟動期間，可以配置相同的設(shè)置來記錄，而不是錯誤輸出：

ALTER DATABASE citus SET citus.multi_task_query_log_level = 'log';

配置參數(shù)部分包含有關(guān)此設(shè)置支持的值的更多信息。

• 配置參數(shù)部分

https://docs.citusdata.com/en/v10.2/develop/api_guc.html#multi-task-logging

遷移生產(chǎn)數(shù)據(jù)

此時，已更新數(shù)據(jù)庫 schema 和應用程序查詢以與 Citus 一起使用，您已準備好進行最后一步。是時候?qū)?shù)據(jù)遷移到 Citus 集群并將應用程序切換到其新數(shù)據(jù)庫了。

數(shù)據(jù)遷移路徑取決于停機時間要求和數(shù)據(jù)大小，但通常屬于以下兩類之一。

• 小型數(shù)據(jù)庫遷移
• 大數(shù)據(jù)庫遷移

小型數(shù)據(jù)庫遷移

對于可以容忍一點停機時間的較小環(huán)境，請使用簡單的 pg_dump/pg_restore 進程。以下是步驟。

從您的開發(fā)數(shù)據(jù)庫中保存數(shù)據(jù)庫結(jié)構(gòu)：

pg_dump \
   --format=plain \
   --no-owner \
   --schema-only \
   --file=schema.sql \
   --schema=target_schema \
   postgres://user:pass@host:5432/db

使用 psql 連接到 Citus 集群并創(chuàng)建 schema：

\i schema.sql

運行您的 create_distributed_table 和 create_reference_table 語句。如果您收到有關(guān)外鍵的錯誤，通常是由于操作順序所致。在分發(fā)表之前刪除外鍵，然后重新添加它們。

將應用程序置于維護模式，并禁用對舊數(shù)據(jù)庫的任何其他寫入。

使用 pg_dump 將原始生產(chǎn)數(shù)據(jù)庫中的數(shù)據(jù)保存到磁盤：

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

測試應用。

運行。

大數(shù)據(jù)庫遷移(Citus Cloud)

較大的環(huán)境可以使用 Citus Warp 進行在線復制。Citus Warp 允許您在更改發(fā)生時將更改從 PostgreSQL 源數(shù)據(jù)庫流式傳輸?shù)? Citus Cloud 集群。就好像應用程序自動寫入兩個數(shù)據(jù)庫而不是一個，除非具有完美的事務邏輯。Citus Warp 可與啟用了 logical_decoding 插件的 Postgres 9.4 及更高版本一起使用(只要您使用的是 9.4 或更高版本，Amazon RDS 就支持此功能)。

對于此過程，我們強烈建議您通過開 ticket、聯(lián)系我們在 Slack 上的解決方案工程師之一或任何適合您的方法來聯(lián)系我們。為了進行 warp，我們通過 VPC 對等或 IP 白名單將 Citus 集群的 coordinator 節(jié)點連接到現(xiàn)有數(shù)據(jù)庫，并開始復制。

以下是開始 Citus Warp 流程之前需要執(zhí)行的步驟：

1. 在目標 Citus 集群上復制 schema 結(jié)構(gòu)
2. 在源數(shù)據(jù)庫中啟用邏輯復制
3. 允許從 Citus coordinator 節(jié)點到源的網(wǎng)絡連接
4. 聯(lián)系我們開始復制

重復 schema

將數(shù)據(jù)遷移到 Citus 的第一步是確保 schema 完全匹配，至少對于您選擇遷移的表而言。一種方法是針對您的開發(fā)數(shù)據(jù)庫(用于本地測試應用程序的 Citus 數(shù)據(jù)庫)運行 pg_dump --schema-only。在 coordinator Citus 節(jié)點上重放輸出。另一種方法是針對目標數(shù)據(jù)庫運行應用程序遷移腳本。

您希望遷移的所有表都必須具有主鍵。相應的目標表也必須具有主鍵，唯一的區(qū)別是這些鍵也允許組合以包含分布列，如識別分布策略中所述。

還要確保在開始復制之前在集群中分布表，這樣數(shù)據(jù)就不必單獨放在 coordinator 節(jié)點上。

啟用邏輯復制

某些托管數(shù)據(jù)庫(例如 Amazon RDS)需要通過更改服務器配置參數(shù)來啟用復制。在 RDS 上，您需要創(chuàng)建一個新參數(shù)組，在其中設(shè)置 rds.logical_replication = 1，然后將參數(shù)組設(shè)為活動參數(shù)組。應用更改需要重新啟動數(shù)據(jù)庫服務器，這可以安排在下一個維護時段。

如果您正在管理自己的 PostgreSQL 安裝，請將這些設(shè)置添加到 postgresql.conf：

wal_level = logical
max_replication_slots = 5 # has to be > 0
max_wal_senders = 5       # has to be > 0

需要重新啟動數(shù)據(jù)庫才能使更改生效。

開放訪問網(wǎng)絡連接

在 Cloud 控制臺中，確定主機名(以 db.citusdata.com 結(jié)尾)。Dig 主機名以找到其 IP 地址：

dig +short <hostname> A

如果您使用的是 RDS，請編輯入站數(shù)據(jù)庫安全組以添加自定義 TCP 規(guī)則：

Protocol

• TCP

Port Range

• 5432

Source

• /32

這會將 Citus coordinator 節(jié)點的 IP 地址列入白名單以進行入站連接。連接兩者的另一種方法是在它們的 VPC 之間建立對等互連。如果需要，我們可以幫助進行設(shè)置。

開始復制

通過在 Citus Cloud 控制臺中打開 support ticket 與我們聯(lián)系。云工程師將使用 Citus Warp 連接到您的數(shù)據(jù)庫，以執(zhí)行初始數(shù)據(jù)庫轉(zhuǎn)儲、打開復制槽并開始復制。我們可以在遷移中包含/排除您選擇的表。

在復制的第一階段，如果數(shù)據(jù)庫處于寫入負載下，Postgres 預寫日志 (WAL) 可能會大幅增長。在開始此過程之前，請確保源數(shù)據(jù)庫上有足夠的磁盤空間。我們建議 100GB 可用空間或總磁盤空間的 20%，以較大者為準。一旦初始 dump/restore 完成并開始復制，那么數(shù)據(jù)庫將能夠再次歸檔未使用的 WAL 文件。

隨著 Warp 的進行，請注意源數(shù)據(jù)庫上的磁盤使用情況。如果源和目標之間存在數(shù)據(jù)類型不匹配，或其他意外的 schema 更改，則復制可能會停止。在長時間停頓期間，復制槽可以在源上無限增長，從而導致潛在的崩潰。

由于復制停滯的可能性，我們強烈建議在進行 Citus warp 時盡量減少 schema 更改。如果需要進行侵入式 schema 更改，您將需要停止 warp 并重試。

進行侵入式 schema 更改的步驟：

1. 請求 Citus Cloud 工程師停止 warp。
2. 更改源數(shù)據(jù)庫上的 schema。
3. 更改目標數(shù)據(jù)庫上的 schema。
4. 再次開始 warp。

切換到 Citus 并停止與舊數(shù)據(jù)庫的所有連接

當復制趕上源數(shù)據(jù)庫的當前狀態(tài)時，還有一件事要做。由于復制過程的性質(zhì)，序列值不會在目標數(shù)據(jù)庫上正確更新。為了獲得正確的序列值，例如 id 列，您需要在打開對目標數(shù)據(jù)庫的寫入之前手動調(diào)整序列值。

一旦這一切完成，應用程序就可以連接到新數(shù)據(jù)庫了。我們不建議同時寫入源數(shù)據(jù)庫和目標數(shù)據(jù)庫。

當應用程序切換到新數(shù)據(jù)庫并且源數(shù)據(jù)庫上沒有發(fā)生進一步的更改時，請再次聯(lián)系我們以刪除復制槽。遷移完成。