Spanner と Liquibase の統合

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

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

Liquibase は、Spanner データベースをターゲットにできます。Spanner のすべての機能をサポートしていますが、いくつかの制限があります。

一般的な制限事項については、制限事項をご覧ください。
Liquibase の要件、サポートされている変更タイプ、制限事項など、PostgreSQL 言語データベースに関する追加情報については、PGAdapter と Liquibase をご覧ください。

Liquibase をインストールする

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

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 言語データベースの場合のみ、Liquibase インストールと同じマシンで PGAdapter が起動し、実行していることを確認します。詳細については、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 スタートガイドをご覧ください。