將 Spanner 遷移至 PostgreSQL 方言資料庫

如要將應用程式從 Spanner 或 Google Cloud移出，本頁面說明瞭從 Spanner 遷移至其他 PostgreSQL 方言資料庫時的關鍵考量和步驟。如果您需要瞭解或證明遷移資料庫的可行性，例如為緊急離開災難規劃，也可以使用本頁面提供的資訊。

如果應用程式需要在 Google Cloud內或其他地方部署至其他與 PostgreSQL 相容的環境，Spanner 的 PostgreSQL 介面是最佳選擇。PostgreSQL 介面採用 PostgreSQL 生態系統中的熟悉語法和標準用戶端，讓開發人員和作業人員運用現有的 PostgreSQL 知識和技能。

與 GoogleSQL 方言一樣，它會使用相同的查詢處理、交易協調、分散式儲存空間和網路基礎架構。如果您需要支援可攜性的資料庫，選擇 PostgreSQL 介面時，您不必犧牲 Spanner 的核心可擴充性、一致性或價格效益。

進一步瞭解 Spanner 中的 PostgreSQL 和 GoogleSQL 方言之間的差異。

大致步驟如下：

1. 從查詢和 DDL 陳述式中移除 Spanner 專屬擴充功能
2. 遷移結構定義
3. 遷移資料
4. 遷移應用程式

Spanner 專屬考量

Spanner 的 PostgreSQL 介面可原生支援 PostgreSQL 查詢，因此在 Spanner PostgreSQL 方言資料庫上執行的大部分 SQL 查詢，其行為與其他與 PostgreSQL 相容的資料庫相同。採用這種做法，從一個平台將應用程式移至另一個平台時，所需的 SQL 和資料存取變更數量可能會很少。這樣一來，相較於類似的 GoogleSQL 方言資料庫，轉移程序就會更快速、更容易，且不易發生錯誤。

除了廣泛的 PostgreSQL 相容性之外，PostgreSQL 介面還提供許多 Spanner 專屬的擴充功能。如果您在應用程式中使用這些擴充功能，就必須手動移除或將這些擴充功能對應至 PostgreSQL 功能。查詢語法擴充功能和結構定義管理 (DDL) 擴充功能中提供了一些值得注意的範例。

查詢語法擴充功能

Spanner 的 PostgreSQL 介面提供多個 Spanner 專屬擴充功能。大多數使用 spanner. 前置字串進行識別。下表列出這些擴充功能，以及在同一個應用程式可在 PostgreSQL 資料庫上執行前，您可能需要採取的動作。

擴充功能類型	特定擴充功能	遷移前須知
Spanner 專屬函式	數學函式清單中列出的向量函式，前置字串為 spanner. 機器學習函式 雜湊函式 日期和時間函式 提交時間戳記函式。 JSONB 函式 使用 spanner. 前置字串的序列函式 公用函式	找出前置字串為 spanner. 的函式，然後移除這些呼叫。
類型擴充功能	使用 VECTOR LENGTH 參數的陣列資料類型	移除 VECTOR LENGTH 語法，或考慮使用 pgvector。
查詢語法	Spanner 查詢提示	系統會在註解中顯示提示，因此您不需要採取任何行動。 如要進一步瞭解效能考量事項，請參閱「查詢遷移」一文。
儲存的系統程序	查詢取消	移除對 spanner.cancel_query() 的呼叫。 您可以選擇將呼叫替換為 PostgreSQL 等同。
SET/SHOW 作業		可忽略，因為 PostgreSQL 沒有任何以 spanner. 開頭的內建參數，因此使用該前置字元設定任何變數不會對預期行為造成任何影響。

結構定義管理 (DDL) 擴充功能

Spanner 提供多種與資料管理相關的擴充功能，詳情請參閱「資料定義語言 (DDL)」頁面。

擴充功能	遷移前須知
交錯式資料表 在實體儲存空間中將多對一相關資料放置在同一位置，讓兩者之間的聯結更有效率。	移除 INTERLEAVE IN 子句。
修訂時間戳記 啟用可將交易的修訂時間戳記以不可分割的形式儲存到資料欄。	請將 SPANNER.COMMIT_TIMESTAMP 替換為 PostgreSQL 時間戳記類型，並管理應用程式中的時間戳記設定，或是移除該欄。
時間點復原 可防止資料意外遭到刪除或寫入。	移除任何設定 spanner.version_retention_period 的 DDL 陳述式。
存留時間 (TTL) 提示系統根據記錄年齡自動刪除記錄。	移除 TTL INTERVAL 子句。建議您使用 cron 或排程工作，定期刪除過時的資料。列。
最佳化工具選項 設定選項，以便在查詢最佳化工具或統計資料變更時，盡可能減少任何可能的效能回溯。	移除設定最佳化工具選項的 DDL 陳述式。
變更串流 以近乎即時的方式，監控並串流輸出 Spanner 資料庫的資料變更 (插入、更新和刪除)。	移除任何與變更串流相關的 DDL 陳述式。
預設領導者 可讓您在雙區域和多區域設定中指定資料庫的領導者。	移除任何設定 spanner.default_leader 的 DDL 陳述式。
地理區域分區 可讓您為不同執行個體設定中的資料庫資料表，進一步區隔及儲存資料列。	移除與地理區隔相關的任何 DDL 陳述式。
序列 Spanner 僅支援 bit_reversed_positive 序列。	將 bit_reversed_positive 替換為 PostgreSQL 中可用的序列。移除任何設定 spanner.default_sequence_kind 的 DDL 陳述式。
區域群組 可讓您定義資料欄群組策略，以便個別儲存資料欄或使用分層儲存空間。	移除與區域群組相關的任何 DDL 陳述式。
搜尋索引 可讓您定義索引，以便執行全文搜尋。	移除與搜尋索引相關的任何 DDL 陳述式。

結構定義遷移

您可以使用 PostgreSQL 語法匯出 PostgreSQL 方言資料庫結構定義。如果資料庫已設定為使用 PostgreSQL 介面，您可以使用 psql 搭配 PGAdapter 來達成這項目標。這個附屬代理程式可讓您使用標準 PostgreSQL 驅動程式或用戶端程式庫，連線至 Spanner：

psql -v ON_ERROR_STOP=1 \
  --host "$PGADAPTER_HOST" \
  --port "$PGADAPTER_PORT" \
  --dbname "$SPANNER_DATABASE" \
  -qAtX \
  -c "show database ddl"

您也可以使用下列 gcloud 指令，將結構定義輸出為與 PostgreSQL 相容的 SQL 指令碼：

gcloud spanner databases ddl describe databasename

如果資料庫使用 Spanner 專屬的結構定義擴充功能 (例如「結構定義管理擴充功能」一文所述的擴充功能)，您執行這項指令時，系統會列出這些擴充功能。您必須先移除這些項目，再將結構定義遷移至 PostgreSQL。

資料遷移

Spanner 的 PostgreSQL 介面支援使用 PGAdapter 的 PostgreSQL COPY TO STDIN 和 STDOUT 擴充功能。這是將資料載入 Spanner 和從 Spanner 載出資料的一種方式。如要進一步瞭解 COPY 指令，請參閱 Spanner 說明文件中的 psql 指令列工具。

這個指令碼會將較少量的資料 (建議為 100 GB 以下) 從 Spanner 的 PostgreSQL 介面匯出至新的 PostgreSQL 資料庫：

psql -h pgadapter-host -c "COPY $TABLE TO STDOUT BINARY" | \
psql -h postgresql-host -c "COPY $TABLE FROM STDIN BINARY"

如果是較大的資料表 (資料量大於或等於 100 GB)，您可以啟動將資料流程匯出至 CSV 範本。

您可以使用 Debezium Kafka 連接器執行即時資料遷移作業，將 Spanner 更新串流傳送至 PostgreSQL。如果您使用 Spanner Change Streams API 直接存取變更資料擷取 (CDC) 串流，就可以進一步自訂。

查詢遷移

Spanner 適用的 PostgreSQL 介面會實作大部分常見的 PostgreSQL 查詢語法、函式和運算子。

如果您在查詢中使用提示，則無需重寫查詢，因為 Spanner 上的查詢提示是在與 PostgreSQL 相容的註解中定義：

SELECT s.FirstName, s.LastName,
 s.SingerInfo, a.AlbumTitle, a.Charts
FROM Singers AS s
LEFT OUTER JOIN/*@JOIN_METHOD=APPLY_JOIN*/ Albums AS a
 ON s.SingerId = a.SingerId;

這些註解會由 Spanner 的查詢規劃工具處理，但 PostgreSQL 資料庫會忽略這些註解，因此您可以選擇是否要加入或移除這些註解。

為了在新環境中發揮最佳效能，查詢和資料庫結構定義 (例如索引) 可能需要針對新環境進行最佳化。建議您執行基準測試，以實證方式確認這項資訊。

遷移應用程式

就應用程式連線而言，遷移策略取決於設定應用程式使用 Spanner 時所做的初始選擇，例如使用 PostgreSQL 驅動程式、Spanner 驅動程式或 Spanner 用戶端程式庫。本節將說明各個選項的考量因素。

PostgreSQL 驅動程式

Spanner 支援使用 PGAdaper 的常見 PostgreSQL 用戶端，這是一種輕量 Proxy，可將 PostgreSQL 線路通訊協定轉譯為 Spanner 的低階 gRPC 查詢 API。如果您使用其中一種，變更為其他 PostgreSQL 目標時，請更新連線字串，直接指向新的 PostgreSQL 資料庫，而非 PGAdapter 代理程式。這種方法可提供良好的效能和強大的相容性，因此如果可移植性是首要考量，就很適合採用這種方法。在 Spanner 的 PostgreSQL 介面上執行的大部分查詢，在其他 PostgreSQL 環境中也能正常運作。不過，反之則不一定成立；PostgreSQL 支援 Spanner 不支援的語法和功能。

Spanner 驅動程式

這些驅動程式是針對常見語言和應用程式架構的 Spanner 專屬實作項目。舉例來說，Spanner JDBC (Java) 驅動程式實作 PostgreSQL JDBC 驅動程式實作的相同 API，因此使用 Spanner JDBC 驅動程式的應用程式在想要透過 PostgreSQL 執行應用程式時，可以更新建構程序，以連結等效的內建 PostgreSQL 驅動程式。如果您已在使用 Spanner，或是想要尋找可運用 Spanner 功能 (例如 Mutations API) 的效能解決方案，而這類功能無法透過內建 PostgreSQL 驅動程式提供，則這個選項最適合您。如果您需要與內建驅動程式和值可攜性完全相容，建議您改為使用 PGAdapter 搭配 PostgreSQL 內建驅動程式，確保應用程式可攜性達到一定程度。

詳情請參閱「PostgreSQL 驅動程式和 ORM」。

Spanner 用戶端程式庫

Spanner 也提供各種慣用用戶端程式庫，可直接存取 Spanner，而無需實作或透過 PostgreSQL 標準化介面。這些用戶端可提供對 Spanner 專屬功能的最大存取權，但與 PostgreSQL 驅動程式的 API 不相容。這些選項可提供最高層級的功能效能，但可移植性不如前述選項。

後續步驟

• 瞭解如何選擇 PostgreSQL 和 GoogleSQL。
• 請按照快速入門的說明建立 PostgreSQL 資料庫並與其互動。
• 進一步瞭解 Spanner 的 PostgreSQL 語言支援功能。
• 瞭解 PGAdapter。
• 瞭解 PGAdapter GitHub 存放區。
• 查看 PostgreSQL 介面中的已知問題。