將 Spanner 與 Liquibase 整合

本頁面說明如何使用 Liquibase 管理 GoogleSQL 方言資料庫和 PostgreSQL 方言資料庫的 Spanner 資料庫結構定義變更。

Liquibase 是開放原始碼的資料庫獨立程式庫，可追蹤、管理及套用資料庫結構定義變更。支援 SQL，以及 XML、YAML 和 JSON 等宣告式格式。

Liquibase 可以指定 Spanner 資料庫。支援所有 Spanner 功能，但有部分限制。

• 如要查看一般限制，請參閱「限制」一節。
• 如要查看 PostgreSQL 方言資料庫的其他資訊，例如 Liquibase 需求、支援的變更類型和限制，請參閱「 PGAdapter 和 Liquibase」。

安裝 Liquibase

如要搭配 GoogleSQL 方言資料庫使用 Liquibase，請安裝 Spanner Liquibase 擴充功能。對於 PostgreSQL 方言資料庫，Liquibase 可以搭配使用內建的 PostgreSQL 支援功能和 PGAdapter。

GoogleSQL

1. 按照 Liquibase 說明文件中的操作說明安裝及設定 Liquibase，並為資料庫建立快照。

2. 前往 GitHub 的 Spanner Liquibase 擴充功能版本頁面，然後選取最新版本。

3. 選取並下載名為 liquibase-spanner-x.y.z-all.jar 的 JAR 檔案，其中 x.y.z 代表擴充功能版本號碼。例如：liquibase-spanner-4.17.0-all.jar。

4. 將下載的 JAR 檔案放在 Liquibase lib 目錄中。JAR 檔案包含擴充功能、Spanner SDK 和 Spanner JDBC 驅動程式。

在 liquibase.properties 設定檔中，將 url 屬性設為如下所示。

 jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE
 

liquibase.properties 設定檔只能包含這項屬性。其他屬性則為選填。

PostgreSQL

1. 請確認 PGAdapter 已啟動並在安裝 Liquibase 的機器上執行。詳情請參閱「啟動 PGAdapter」。

2. 按照 Liquibase 說明文件中的操作說明安裝及設定 Liquibase，並為資料庫建立快照。

在 liquibase.properties 設定檔中，將 url 屬性設為如下所示。

  jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
  

liquibase.properties 設定檔只能包含這項屬性。其他屬性則為選填。

url 字串必須包含 options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction，因為 Spanner 不支援 DDL 交易，而這可確保 DDL 交易會轉換為 DDL 批次。詳情請參閱「PGAdapter 的 DDL 選項」。

查看 Liquibase 範例

GoogleSQL

GoogleSQL Liquibase 擴充功能隨附的範例變更記錄檔 changelog.yaml，示範了 Liquibase 的許多功能，以及如何搭配 Spanner 使用這些功能。

PostgreSQL

PGAdapter 和 Liquibase GitHub 存放區提供的範例變更記錄檔 dbchangelog.xml，說明瞭 Liquibase 的許多功能，以及如何搭配 Spanner 使用這些功能。

Liquibase 快速入門導覽課程

本快速入門導覽課程說明如何使用 Liquibase 將 Singers 資料表新增至資料庫。

事前準備

• 請確認您已完成先前的步驟，安裝 Liquibase。

• 建立 Spanner 執行個體。

• 建立 GoogleSQL 方言資料庫或 PostgreSQL 方言資料庫。

• 如果資料庫僅使用 PostgreSQL 方言，請確保 PGAdapter 已啟動並在 Liquibase 安裝所在的機器上執行。詳情請參閱「啟動 PGAdapter」。

• 如果是 PostgreSQL 方言資料庫，請使用 create_database_change_log.sql 指令碼建立 databasechangeloglock 和 databasechangelog 中繼資料表。您必須建立這些資料表，才能覆寫 Liquibase 在資料庫中自動建立的資料表。這是為了確保這些資料表使用正確的 Spanner PostgreSQL 資料類型。

  您可以執行下列指令來執行指令碼：

  psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql
  

• 執行下列 gcloud 指令，讓 Spanner Liquibase 擴充功能暫時使用您的 Spanner 使用者憑證存取 API：

  gcloud auth application-default login
  

建立 changelog.yaml

1. 在慣用的編輯器中輸入下列 YAML。

   databaseChangeLog:
     - preConditions:
        onFail: HALT
        onError: HALT
   
     - changeSet:
        id: create-singers-table
        author: spanner-examples
        changes:
          - createTable:
             tableName: Singers
             columns:
               -  column:
                   name:    SingerId
                   type:    BIGINT
                   constraints:
                     primaryKey: true
                     primaryKeyName: pk_Singers
               -  column:
                   name:    Name
                   type:    VARCHAR(255)
   

   這個 YAML 會定義名為 Singers 的資料表，其中包含主鍵 SingerId 和名為 Name 的資料欄，用於儲存歌手姓名。

   如果是 PostgreSQL 方言資料庫，建議您使用全小寫的資料表和資料欄名稱。詳情請參閱 PostgreSQL 區分大小寫。

   請注意，createTable 變更集必須包含主鍵限制，且主鍵限制的名稱必須為 pk_table_name。

2. 將變更儲存為 changelog.yaml。

執行 Liquibase

在 changelog.yaml 中執行下列指令，套用變更集：

liquibase --changeLogFile changelog.yaml update

Liquibase 會使用您在 liquibase.properties 檔案中定義的網址。如要覆寫檔案中的值，請在上述指令中加入下列引數：

--url URL

確認變更

由於您在上一個步驟中進行更新，Singer 資料表已新增至資料庫。此外，系統也新增 (GoogleSQL 方言資料庫) 或更新 (PostgreSQL 方言資料庫) 了 DATABASECHANGELOG 和 DATABASECHANGELOGLOCK 資料表。

您可以透過 Google Cloud 控制台或 gcloud CLI 驗證這些資料表是否存在。舉例來說，執行 SQL 查詢 SELECT * FROM INFORMATION_SCHEMA.TABLES 會傳回資料庫中的所有資料表清單。

gcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \
    --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'

您可以查詢 DATABASECHANGELOG 的內容，查看套用的變更記錄。

後續步驟

• 如需更多文件，請前往 Spanner Liquibase 擴充功能 GitHub 存放區。

• 如要進一步瞭解 Liquibase，請參閱「開始使用 Liquibase」。