このページでは、Spanner 変更ストリームを作成、変更、表示する方法について説明します。変更ストリームの詳細については、変更ストリームについてをご覧ください。
変更ストリームはスキーマ オブジェクトであるため、他の種類のデータベース定義作業（データセットの作成やインデックスの追加など）に使用されるものと同じ DDL によるスキーマ更新を使用して作成、管理します。
Spanner は、スキーマを変更する DDL ステートメント（変更ストリームの作成、変更、削除に使用されたステートメントを含む）を送信すると、長時間実行オペレーションを開始します。新規または変更された変更ストリームは、この長時間実行オペレーションの完了時に、新しい構成で指定された列やテーブルのモニタリングを開始します。
変更ストリームを作成
変更ストリームを作成するには、その名前と監視するスキーマ オブジェクト（データベース全体か、特定のテーブルと列のリスト）を指定する必要があります。必要に応じて、次を指定できます。
- 1 日間のデフォルトの保持期間をオーバーライドする保持期間
- デフォルト値のキャプチャ タイプ
OLD_AND_NEW_VALUESをオーバーライドする値キャプチャ タイプ。 - 変更ストリームから TTL ベースの削除を除外する場合、TTL ベースの削除フィルタ
INSERT、UPDATE、DELETEのすべてのテーブルの変更を除外するテーブル変更の除外
GoogleSQL
GoogleSQL を使用して変更ストリームを作成する DDL 構文は、次のようになります。
CREATE CHANGE STREAM change_stream_name [FOR column_or_table_watching_definition[, ... ] ] [ OPTIONS ( retention_period = timespan, value_capture_type = type, exclude_ttl_deletes = boolean, exclude_insert = boolean, exclude_update = boolean, exclude_delete = boolean ) ]
PostgreSQL
PostgreSQL を使用して変更ストリームを作成する DDL 構文は次のようになります。
CREATE CHANGE STREAM change_stream_name [FOR column_or_table_watching_definition[, ... ] ] [ WITH ( retention_period = timespan, value_capture_type = type, exclude_ttl_deletes = boolean, exclude_insert = boolean, exclude_update = boolean, exclude_delete = boolean ) ]
新しい変更ストリームは、作成した長時間実行オペレーションが完了するとすぐに、割り当てられたスキーマ オブジェクトの監視を開始します。
次の例では、さまざまな構成で変更ストリームを作成する方法を示します。
データベース全体を監視する
データベースのテーブル全体で行われるすべてのデータ変更を監視する変更ストリームを作成するには、ALL キーワードを使用します。
CREATE CHANGE STREAM EverythingStream
FOR ALL;
ALL 構成では、今後作成されるデータべースのデータテーブルと列がすべて、すぐに暗黙的に含まれます。ビュー、情報スキーマ テーブル、などの通常のデータテーブル以外のオブジェクトは含まれません。
特定のテーブルを監視する
変更ストリームのスコープをデータベース全体ではなく特定のテーブルに制限するには、1 つ以上のテーブルのリストを指定します。
CREATE CHANGE STREAM SingerAlbumStream
FOR Singers, Albums;
Spanner は、テーブル全体を監視する変更ストリームを自動的に更新し、列の追加や削除など、テーブルに影響するスキーマの変更を反映します。
特定の列を監視する
table(column_1[, column_2,
...]) 構文を使用して、指定したテーブル内にある 1 つ以上の特定の非キー列に対する変更を監視します。
CREATE CHANGE STREAM NamesAndTitles
FOR Singers(FirstName, LastName), Albums(Title);
すべての変更ストリームは、監視対象のすべてのテーブルの主キーを常時追跡するため、主キー列を指定することはできません。これにより、すべてのデータ変更レコードは変更された行を主キーで識別できます。
テーブルと列を 1 つのストリームで監視する
上記の 2 つの例のテーブル監視構文と列監視構文は、1 つの変更ストリームと組み合わせることができます。
CREATE CHANGE STREAM NamesAndAlbums
FOR Singers(FirstName, LastName), Albums;
長い保持期間を指定する
変更ストリーム データの保持期間をデフォルトの 1 日よりも長く指定するには、retention_period を最大 1 週間の期間（時間（h）または日（d））に設定します。
2 つの例を次に示します。
GoogleSQL
CREATE CHANGE STREAM LongerDataRetention
FOR ALL
OPTIONS ( retention_period = '36h' );
CREATE CHANGE STREAM MaximumDataRetention
FOR ALL
OPTIONS ( retention_period = '7d' );
PostgreSQL
CREATE CHANGE STREAM LongerDataRetention
FOR ALL
WITH ( retention_period = '36h' );
CREATE CHANGE STREAM MaximumDataRetention
FOR ALL
WITH ( retention_period = '7d' );
別の値キャプチャ タイプを指定する
OLD_AND_NEW_VALUES 以外の変更ストリーム値キャプチャ タイプを指定するには、value_capture_type を NEW_VALUES または NEW_ROW に設定します。次に例を示します。
GoogleSQL
CREATE CHANGE STREAM NewRowChangeStream
FOR ALL
OPTIONS ( value_capture_type = 'NEW_ROW' );
CREATE CHANGE STREAM NewValuesChangeStream
FOR ALL
OPTIONS ( value_capture_type = 'NEW_VALUES' );
PostgreSQL
CREATE CHANGE STREAM NewRowChangeStream
FOR ALL
WITH ( value_capture_type = 'NEW_ROW' );
CREATE CHANGE STREAM NewValuesChangeStream
FOR ALL
WITH ( value_capture_type = 'NEW_VALUES' );
TTL ベースの削除をフィルタ
exclude_ttl_deletes フィルタを使用して、変更ストリームのスコープから TTL ベースの削除をフィルタリングできます。
このフィルタの仕組みの詳細については、有効期間に基づく削除フィルタをご覧ください。
GoogleSQL
TTL ベースの削除フィルタを使用して変更ストリームを作成するには、次を使用します。
CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
OPTIONS (exclude_ttl_deletes = true)
次のように置き換えます。
- CHANGE_STREAM_NAME: 新しい変更ストリームの名前
次の例では、TTL ベースのすべての削除を除外する NewFilterChangeStream という名前の変更ストリームを作成します。
CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
OPTIONS (exclude_ttl_deletes = true)
PostgreSQL
TTL ベースの削除フィルタを使用して変更ストリームを作成するには、次を使用します。
CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
WITH (exclude_ttl_deletes = true)
次のように置き換えます。
- STREAM_NAME: 新しい変更ストリームの名前
次の例では、TTL ベースのすべての削除を除外する NewFilterChangeStream という名前の変更ストリームを作成します。
CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
WITH (exclude_ttl_deletes = true)
既存の変更ストリームに TTL ベースの削除フィルタを追加または削除するには、TTL ベースの削除フィルタを変更するをご覧ください。 変更ストリーム フィルタを確認するには、DDL として変更ストリームの定義を表示します。
テーブル変更タイプでのフィルタ
次の使用可能なフィルタ オプションを使用して、変更ストリームのスコープからこれらのテーブル変更を 1 つ以上フィルタリングします。
exclude_insert: すべてのINSERTテーブルの変更を除外するexclude_update: すべてのUPDATEテーブルの変更を除外するexclude_delete: すべてのDELETEテーブルの変更を除外する
これらのフィルタの仕組みの詳細については、テーブル変更タイプのフィルタをご覧ください。
GoogleSQL
1 つ以上のテーブル変更タイプのフィルタを使用して変更ストリームを作成するには、以下を使用します。
CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
OPTIONS (MOD_TYPE_FILTER_NAME = true)
次のように置き換えます。
- CHANGE_STREAM_NAME: 新しい変更ストリームの名前
- MOD_TYPE_FILTER_NAME: 追加するフィルタ（
exclude_insert、exclude_update、exclude_delete）。 一度に複数のフィルタを追加する場合は、各フィルタをカンマで区切ります。
次の例では、INSERT と UPDATE のテーブル変更タイプを除外する NewFilterChangeStream という名前の変更ストリームを作成します。
CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
OPTIONS (exclude_insert = true, exclude_update = true)
PostgreSQL
1 つ以上のテーブル変更タイプのフィルタを使用して変更ストリームを作成するには、以下を使用します。
CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
WITH (MOD_TYPE_FILTER_NAME = true)
次のように置き換えます。
- CHANGE_STREAM_NAME: 既存の変更ストリームの名前
- MOD_TYPE_FILTER_NAME: 追加するフィルタ（
exclude_insert、exclude_update、exclude_delete）。 一度に複数のフィルタを追加する場合は、各フィルタをカンマで区切ります。
次の例では、INSERT と UPDATE のテーブル変更トランザクション タイプを除外する NewFilterChangeStream という名前の変更ストリームを作成します。
CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
WITH (exclude_insert = true, exclude_update = true)
既存の変更ストリームにテーブル変更タイプのフィルタを追加または削除するには、テーブル変更タイプでのフィルタを変更するをご覧ください。変更ストリームに存在するテーブル変更タイプのフィルタは、変更ストリームの定義を DDL として表示することで確認できます。
変更ストリームを変更する
変更ストリームの構成を変更するには、ALTER CHANGE STREAM DDL ステートメントを使用します。CREATE CHANGE STREAM と同様の構文を使用します。ストリームの監視対象の列やデータ保持期間の長さは変更できます。データ変更レコードを保持しながら、監視を全体で一時停止することもできます。
変更ストリームの監視対象を変更する
この例では、Songs テーブル全体を以前に構成した NamesAndAlbums 変更ストリームに追加します。
ALTER CHANGE STREAM NamesAndAlbums
SET FOR Singers(FirstName, LastName), Albums, Songs;
Spanner は、データベースのスキーマ内の変更ストリーム定義を更新する長時間実行オペレーションの完了時に、指定された変更ストリームの動作を新しい構成に置き換えます。
変更ストリームのデータ保持期間を変更する
変更ストリームが内部レコードを保持する期間を変更するには、ALTER CHANGE STREAM DDL ステートメントで retention_period を設定します。
この例では、以前に作成した NamesAndAlbums 変更ストリームに対してデータ保持期間を調整します。
GoogleSQL
ALTER CHANGE STREAM NamesAndAlbums
SET OPTIONS ( retention_period = '36h' );
PostgreSQL
ALTER CHANGE STREAM NamesAndAlbums
SET ( retention_period = '36h' );
変更ストリームの値キャプチャ タイプを変更する
変更ストリームの値キャプチャ タイプを変更するには、ALTER CHANGE STREAM DDL ステートメントで value_capture_type 句を設定します。
この例では、値キャプチャ タイプを NEW_VALUES に調整しています。
GoogleSQL
ALTER CHANGE STREAM NamesAndAlbums
SET OPTIONS ( value_capture_type = 'NEW_VALUES' );
PostgreSQL
ALTER CHANGE STREAM NamesAndAlbums
SET ( value_capture_type = 'NEW_VALUES' );
TTL ベースの削除フィルタを変更する
変更ストリームの TTL ベースの削除フィルタを変更するには、ALTER CHANGE STREAM DDL ステートメントで exclude_ttl_deletes フィルタを設定します。これにより、既存の変更ストリームにフィルタを追加したり、既存の変更ストリームからフィルタを削除したりできます。
これらのフィルタの仕組みの詳細については、有効期間に基づく削除フィルタをご覧ください。
既存の変更ストリームに TTL ベースの削除フィルタを追加する
GoogleSQL
TTL ベースの削除フィルタを既存の変更ストリームに追加するには、次のコマンドを使用してフィルタを true に設定します。
ALTER CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
SET OPTIONS (exclude_ttl_deletes = true)
次のように置き換えます。
- CHANGE_STREAM_NAME: 既存の変更ストリームの名前
次の例では、TTL ベースのすべての削除を除外する NewFilterChangeStream という名前の既存の変更ストリームに exclude_ttl_deletes フィルタを追加します。
ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET OPTIONS (exclude_ttl_deletes = true)
これにより、変更ストリームから TTL ベースのすべての削除が除外されます。
PostgreSQL
TTL ベースの削除フィルタを既存の変更ストリームに追加するには、次のコマンドを使用してフィルタを True に設定します。
ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET (exclude_ttl_deletes = true)
次のように置き換えます。
- STREAM_NAME: 既存の変更ストリームの名前
次の例では、exclude_ttl_deletes フィルタが NewFilterChangeStream という名前の既存の変更ストリームに追加されます。
ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET (exclude_ttl_deletes = true)
これにより、変更ストリームから将来のすべての TTL ベースの削除が除外されます。
既存の変更ストリームから TTL ベースの削除フィルタを削除する
GoogleSQL
既存の変更ストリームに対する TTL ベースの削除フィルタを削除するには、次のコマンドを使用してフィルタを False に設定します。
ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET OPTIONS (exclude_ttl_deletes = false)
次のように置き換えます。
- STREAM_NAME: 新しい変更ストリームの名前
次の例では、NewFilterChangeStream という名前の既存の変更ストリームから exclude_ttl_deletes フィルタが削除されています。
ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET OPTIONS (exclude_ttl_deletes = false)
これには、変更ストリームに対する将来のすべての TTL ベースの削除が含まれます。
フィルタを null に設定して、TTL ベースの削除フィルタを削除することもできます。
PostgreSQL
既存の変更ストリームに対する TTL ベースの削除フィルタを削除するには、次のコマンドを使用してフィルタを False に設定します。
ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET (exclude_ttl_deletes = false)
次のように置き換えます。
- STREAM_NAME: 新しい変更ストリームの名前
次の例では、NewFilterChangeStream という名前の既存の変更ストリームから exclude_ttl_deletes フィルタが削除されています。
ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET (exclude_ttl_deletes = false)
これには、変更ストリームに対する将来のすべての TTL ベースの削除が含まれます。
フィルタを null に設定して、TTL ベースの削除フィルタを削除することもできます。
テーブル変更タイプでのフィルタを変更する
変更ストリームのテーブル変更タイプのフィルタを変更するには、ALTER CHANGE STREAM DDL ステートメントでフィルタタイプを設定します。これにより、変更ストリームに新しいフィルタを追加したり、既存のフィルタを削除したりできます。
既存の変更ストリームにテーブル変更タイプのフィルタを追加する
GoogleSQL
1 つ以上の新しいテーブル変更タイプのフィルタを既存の変更ストリームに追加するには、次のコマンドを使用してフィルタを true に設定します。
ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET OPTIONS (MOD_TYPE_FILTER_NAME = true)
次のように置き換えます。
- CHANGE_STREAM_NAME: 既存の変更ストリームの名前に置き換えます。
- MOD_TYPE_FILTER_NAME: 追加するフィルタ（
exclude_insert、exclude_update、exclude_delete）に置き換えます。 一度に複数のフィルタを追加する場合は、各フィルタをカンマで区切ります。
次の例では、exclude_delete フィルタが NewFilterChangeStream という名前の既存の変更ストリームに追加されます。
ALTER CHANGE STREAM NewFilterChangeStream
SET OPTIONS (exclude_delete = true)
PostgreSQL
1 つ以上の新しいテーブル変更タイプのフィルタを既存の変更ストリームに追加するには、次のコマンドを使用してフィルタを true に設定します。
ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET (MOD_TYPE_FILTER_NAME = true)
次のように置き換えます。
- CHANGE_STREAM_NAME: 既存の変更ストリームの名前に置き換えます。
- MOD_TYPE_FILTER_NAME: 追加するフィルタ（
exclude_insert、exclude_update、exclude_delete）に置き換えます。 一度に複数のフィルタを追加する場合は、各フィルタをカンマで区切ります。
次の例では、exclude_delete フィルタが NewFilterChangeStream という名前の既存の変更ストリームに追加されます。
ALTER CHANGE STREAM NewFilterChangeStream
SET (exclude_delete = true)
既存の変更ストリームからテーブル変更タイプのフィルタを削除する
GoogleSQL
変更ストリーム内の 1 つ以上の既存のテーブル変更タイプのフィルタを削除するには、次のコマンドを使用してフィルタを false に設定します。
ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET OPTIONS (MOD_TYPE_FILTER_NAME = false)
次のように置き換えます。
- CHANGE_STREAM_NAME: 既存の変更ストリームの名前に置き換えます。
- MOD_TYPE_FILTER_NAME: 削除するフィルタ（
exclude_insert、exclude_update、exclude_delete）に置き換えます。 一度に複数のフィルタを削除する場合は、各フィルタをカンマで区切ります。
次の例では、exclude_delete フィルタが NewFilterChangeStream という名前の既存の変更ストリームから削除されます。
ALTER CHANGE STREAM NewFilterChangeStream
SET OPTIONS (exclude_delete = false)
フィルタをデフォルト値に戻して、テーブル変更フィルタを削除することもできます。そのためには、フィルタ値を null に設定します。
PostgreSQL
変更ストリーム内の 1 つ以上の既存のテーブル変更タイプのフィルタを削除するには、次のコマンドを使用してフィルタを False に設定します。
ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET (MOD_TYPE_FILTER_NAME = false)
次のように置き換えます。
- CHANGE_STREAM_NAME: 既存の変更ストリームの名前に置き換えます。
- MOD_TYPE_FILTER_NAME: 追加するフィルタ（
exclude_insert、exclude_update、exclude_delete）に置き換えます。 一度に複数のフィルタを追加する場合は、各フィルタをカンマで区切ります。
次の例では、exclude_delete フィルタが NewFilterChangeStream という名前の既存の変更ストリームから削除されます。
ALTER CHANGE STREAM NewFilterChangeStream
SET (exclude_delete = false)
フィルタをデフォルト値に戻して、テーブル変更フィルタを削除することもできます。そのためには、フィルタ値を null に設定します。
変更ストリームを一時停止する
変更ストリームがアクティビティを停止しても、少なくともデータ保持期間中は内部レコードを保持したい場合は、変更して何も監視しないように変更できます。
これを行うには、ALTER CHANGE STREAM DDL ステートメントを発行して変更ストリームの定義を特別なフレーズ DROP FOR ALL に置き換えます。例:
ALTER CHANGE STREAM MyStream DROP FOR ALL;
ストリームはデータベースに引き続き存在するものの、オブジェクトの監視は行わず、データ変更レコードも生成しません。既存の変更レコードは、ストリームのデータ保持ポリシーに沿ってそのまま残ります。
一時停止されたストリームを再開するには、以前の構成で別の ALTER CHANGE STREAM ステートメントを発行します。
変更ストリームを削除する
変更ストリームを完全に削除するには、ストリームの名前を指定して DROP CHANGE STREAM ステートメントを発行します。
DROP CHANGE STREAM NamesAndAlbums;
Spanner はストリームを直ちに停止し、データベースのスキーマから削除してデータ変更レコードを削除します。
変更ストリームのリスト化と表示
Google Cloud コンソールには、データベースの変更ストリーム定義をリスト化し確認するためのウェブ インターフェースが用意されています。変更ストリームの構造は、同等の DDL ステートメントとして表示するか、データベースの情報スキーマをクエリして表示することもできます。
Google Cloud コンソールで変更ストリームを表示する
データベースの変更ストリームのリストを表示してその定義を確認するには:
Google Cloud コンソールの Spanner インスタンス ページにアクセスします。
該当するインスタンスとデータベースに移動します。
ナビゲーション メニューで [変更ストリーム] をクリックします。
これにより、そのデータベースのすべての変更ストリームのリストと、それぞれの構成の要約が表示されます。ストリーム名をクリックすると、監視対象のテーブルと列の詳細が表示されます。
DDL として変更ストリームの定義を表示する
データベースのスキーマを DDL として表示すると、すべての変更ストリームの説明が含まれ、それらが CREATE CHANGE STREAM ステートメントとして表示されます。
コンソールからこれを行うには、Google Cloud コンソールのデータベース ページで [同等の DDL を表示] リンクをクリックします。
コマンドラインからこれを行うには、Google Cloud CLI の
ddl describeコマンドを使用します。
変更ストリームに関する情報スキーマをクエリ検索する
変更ストリームについては、データベースの情報スキーマを直接クエリ検索できます。次の表に、変更ストリームの名前、監視するテーブルと列、保持期間を定義するメタデータを示します。
変更ストリームのベスト プラクティス
変更ストリームを構成および管理するためのベスト プラクティスは次のとおりです。
別のメタデータ データベースを検討する
変更ストリームでは、メタデータ データベースを使用して内部状態が維持されます。 メタデータ データベースは、変更ストリームを含むデータベースと同じでも異なっていてもかまいません。メタデータ ストレージ用に別のデータベースを作成することをおすすめします。
Spanner 変更ストリーム コネクタには、メタデータ データベースに対する読み取り / 書き込み権限が必要です。このデータベースをスキーマとともに準備する必要はありません。コネクタがそれに対処します。
別のメタデータ データベースを使用すると、コネクタがアプリケーション データベースに直接書き込む際に発生する複雑性がなくなります。
メタデータ データベースを、変更ストリームを備えた本番環境のデータベースから分離すると、コネクタには、本番環境のデータベースに対する読み取り権限のみが必要になります。
コネクタのトラフィックを別のメタデータ データベースに制限することで、コネクタ自体によって実行される書き込みは本番環境の変更ストリームに含まれません。これは、データベース全体を監視する変更ストリームに特に関連します。
メタデータの保存に別のデータベースを使用していない場合は、インスタンス上の変更ストリーム コネクタの CPU の影響をモニタリングすることをおすすめします。
新しい変更ストリームのベンチマークを行い、必要に応じてサイズ変更を行う
本番環境インスタンスに新しい変更ストリームを追加する前に、変更ストリームを有効にしてステージング インスタンスで現実的なワークロードのベンチマークを実施することを検討してください。これにより、コンピューティング容量とストレージ容量を増やすためにノードをインスタンスに追加する必要があるかどうかを判断できます。
CPU とストレージの指標が安定するまで、これらのテストを実行します。インスタンスの CPU 使用率が推奨最大値を超えないようにするのが理想的です。また、ストレージ使用量がインスタンスのストレージ上限を超えないようにする必要があります。
複数のリージョンを使用して負荷分散を行う
マルチリージョン インスタンス構成で変更ストリームを使用する場合は、デフォルトのリーダー リージョンとは異なるリージョンで処理パイプラインを実行することを検討してください。これにより、リーダー以外のレプリカ間でストリーミングの読み込みを分散処理できます。ただし、負荷分散よりもストリーミングの遅延を可能な限り低減することを優先する必要がある場合は、リーダー リージョンでストリーミングの読み込みを実行します。
次のステップ
テンプレートを使用して、変更ストリームを BigQuery、Cloud Storage、Pub/Sub にすばやく接続する。