Spanner を Liquibase と統合する

このページでは、Liquibase を使用して Spanner データベーススキーマの変更を管理する方法について説明します。

Liquibase は、データベーススキーマの変更を追跡、管理、適用するための、データベースに依存しないオープンソースのライブラリです。SQL だけでなく、XML、YAML、JSON などの宣言型の形式もサポートしています。

Liquibase は Spanner データベースをターゲットにできます。一部の制限付きで、Spanner のすべての機能をサポートしています。

一般的な制限事項については、制限事項をご覧ください。
PostgreSQL 方言データベースの詳細（Liquibase の要件、サポートされている変更タイプ、制限事項など）については、PGAdapter と Liquibase をご覧ください。

Liquibase をインストールする

GoogleSQL 言語データベースで Liquibase を使用するには、Spanner Liquibase 拡張機能をインストールする必要があります。PostgreSQL 言語データベースの場合、Liquibase は PGAdapter と組み合わせて、組み込みの PostgreSQL サポートを使用できます。

GoogleSQL

Liquibase のドキュメントの手順に沿って、Liquibase をインストールし、構成して、データベースのスナップショットを作成します。liquibase.properties 構成ファイルで、url プロパティを次のように設定します。
```
jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE
```
liquibase.properties 構成ファイルには、このプロパティのみを含めることができます。それ以外のプロパティは省略可能です。
GitHub で Cloud Spanner Liquibase 拡張機能のリリースページに移動し、最新リリースを選択します。
liquibase-spanner-x.y.z-all.jar という名前の JAR ファイルを選択してダウンロードします。ここで x.y.z は拡張機能のバージョン番号を表します。例: liquibase-spanner-4.17.0-all.jar
ダウンロードした JAR ファイルを Liquibase の lib ディレクトリに配置します。JAR ファイルには、拡張機能、Spanner SDK、Spanner JDBC ドライバのドライバが含まれています。

PostgreSQL

Liquibase をインストールするマシンで PGAdapter が起動され、実行されていることを確認します。詳細については、PGAdapter を起動するをご覧ください。
Liquibase のドキュメントの手順に沿って、Liquibase をインストールし、構成して、データベースのスナップショットを作成します。liquibase.properties 構成ファイルで、url プロパティを次のように設定します。
```
jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
```
liquibase.properties 構成ファイルには、このプロパティのみを含めることができます。それ以外のプロパティは省略可能です。

Spanner は DDL トランザクションをサポートしていないため、url 文字列に options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction を含める必要があります。これにより、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 コマンドを実行して、API アクセスのために自身の Spanner ユーザー認証情報を　Spanner Liquibase　拡張機能で一時的に使用します。
```
gcloud auth application-default login
```

changelog.yaml を作成する

任意のエディタに次の 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 は、主キー SingerId と、歌手の名前を保存する Name という列を持つ Singers というテーブルを定義します。

PostgreSQL 言語データベースでは、テーブル名と列名にすべて小文字を使用することをおすすめします。詳細については、PostgreSQL の大文字と小文字の区別をご覧ください。

createTable 変更セットには主キー制約を含める必要があり、主キー制約の名前は pk_table_name にする必要があります。

変更を changelog.yaml として保存します。

Liquibase を実行する

次のコマンドを実行して、changelog.yaml の変更セットを適用します。

liquibase --changeLogFile changelog.yaml update

Liquibase は、liquibase.properties ファイルで定義した URL を使用します。ファイル内の値をオーバーライドするには、前のコマンドに次の引数を追加します。

--url URL

変更を確認する

前の手順の更新により、Singer テーブルがデータベースに追加されました。また、DATABASECHANGELOG テーブルと DATABASECHANGELOGLOCK テーブルが追加（GoogleSQL 言語データベース）または、更新（PostgreSQL 言語データベース）されました。

これらのテーブルの存在は、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 スタートガイドをご覧ください。