gcloud で Cloud Spanner を使ってみる

目標

このチュートリアルでは、gcloud コマンドライン ツールを使用する次の手順について説明します。

  • Cloud Spanner のインスタンス、データベース、スキーマを作成する
  • データベースにデータを書き込み、そのデータに対して SQL クエリを実行する
  • データベースとインスタンスを削除してクリーンアップする

完全な gcloud spanner リファレンスについては、gcloud Spanner をご覧ください。

費用

このチュートリアルで使用する Cloud Spanner は、Google Cloud の有料コンポーネントです。Cloud Spanner を使用する料金については、料金をご覧ください。

始める前に

  1. 設定に示されている手順を完了します。この手順では、Google Cloud のデフォルト プロジェクトの作成と設定、課金の有効化、Cloud Spanner API の有効化、Cloud Spanner API を使用するのに必要な認証情報を取得するための OAuth 2.0 の設定を行います。
    特に、ローカル開発環境で認証情報を設定するために、必ず gcloud auth application-default login を実行してください。

デフォルト プロジェクトの設定

まだ行っていない場合には、Google Cloud Platform プロジェクトの ID を gcloud コマンドライン ツールのデフォルト プロジェクトに設定します。

gcloud config set project PROJECT_ID

デフォルトのプロジェクトを設定しない場合は、次の各コマンドに gcloud spanner の最初の引数として --project PROJECT_ID を渡す必要があります。例:

gcloud spanner --project=PROJECT_ID instance-configs list

インスタンス

Cloud Spanner を最初に使用するときは、インスタンスを作成する必要があります。これにより、Cloud Spanner データベースによって使用されるリソースを割り当てます。インスタンスを作成するときに、データの格納場所とデータに使用するノード数を選択します。

インスタンスとインスタンス構成

インスタンスを作成するにはインスタンス構成を選択する必要があります。この構成は Cloud Spanner データの地理的配置とレプリケーションを定義するインスタンスの設計図のようなものです。

インスタンス設定の一覧取得

インスタンスの作成時には「インスタンス構成」を指定し、そのインスタンスのデータベースの地理的位置とレプリケーションを定義します。1 つのリージョンにデータを格納するリージョン構成、または複数のリージョンにデータを分散するマルチ リージョン構成を選択できます。詳しくは、インスタンスをご覧ください。

プロジェクトで使用可能なインスタンス構成の一覧を表示するには、次のコマンドを実行します。

gcloud spanner instance-configs list

リージョンおよびマルチリージョン構成の一覧が表示されます。

リージョン構成ではデータが単一のリージョン内に分散され、マルチリージョン構成ではデータが地理的に複数のリージョンにわたって分散されます。詳細については、インスタンスをご覧ください。

インスタンスの作成

1 ノードのリージョン インスタンス設定 regional-us-central1 を使用して、表示名 My Instance を持つ test-instance という名前のインスタンスを作成する場合は、以下の操作を実行します。

gcloud spanner instances create test-instance --config=regional-us-central1 \
    --description="My Instance" --nodes=1

上記のコマンドでは、インスタンス名は test-instance と設定され、インスタンスの表示名は --description と設定されています。これらの両方の値が Google Cloud Platform プロジェクト内で一意である必要があります。

デフォルトのインスタンスの設定

コマンドにインスタンスが指定されていないときに Cloud Spanner が使用するデフォルトのインスタンスを設定できます。デフォルトのインスタンスを設定するには、次のコマンドを実行します。

gcloud config set spanner/instance test-instance

データベースの作成

example-db という名前のデータベースを作成します。

gcloud spanner databases create example-db

スキーマの作成

Cloud Spanner の データ定義言語(DDL)はテーブルの作成、変更、削除、またはインデックスの作成や削除に使用されます。

2 つのテーブルを作成してみましょう

gcloud spanner databases ddl update example-db \
  --ddl='CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)'
gcloud spanner databases ddl update example-db \
  --ddl='CREATE TABLE Albums ( SingerId INT64 NOT NULL, AlbumId INT64 NOT NULL, AlbumTitle STRING(MAX)) PRIMARY KEY (SingerId, AlbumId), INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

データを書き込む

データベースにサンプルデータを追加しましょう

gcloud spanner rows insert --database=example-db \
      --table=Singers \
      --data=SingerId=1,FirstName=Marc,LastName=Richards

gcloud spanner rows insert --database=example-db \
      --table=Singers \
      --data=SingerId=2,FirstName=Catalina,LastName=Smith

gcloud spanner rows insert --database=example-db \
      --table=Singers \
      --data=SingerId=3,FirstName=Alice,LastName=Trentor

gcloud spanner rows insert --database=example-db \
      --table=Albums \
      --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk"

gcloud spanner rows insert --database=example-db \
      --table=Albums \
      --data=SingerId=2,AlbumId=1,AlbumTitle="Green"

gcloud spanner rows insert --database=example-db \
      --table=Albums \
      --data=^:^SingerId=2:AlbumId=2:AlbumTitle="Go, Go, Go"

デフォルトでは、リスト内のアイテムはカンマで区切ります。最後の挿入コマンドでは、区切り文字としてコロン(^:^)を指定したため、アルバムのタイトルにカンマを使用できました。

SQL を使用したデータのクエリ

コマンドラインでクエリを実行します。

gcloud spanner databases execute-sql example-db \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

Cloud Spanner SQL リファレンスについてはクエリ構文をご覧ください。

execute-sql コマンドで使用できるフラグのリストについては、gcloud Spanner データベースの exit-sql をご覧ください。

クリーンアップ

このチュートリアルで使用したリソースについて Google Cloud アカウントに課金されないようにするため、作成したデータベースとインスタンスを削除します。

データベースの削除

既存のインスタンスを削除するには、次のコマンドを実行します。

gcloud spanner databases delete example-db

インスタンスの削除

既存のインスタンスを削除するには、次のコマンドを実行します。

gcloud spanner instances delete test-instance

インスタンスを削除すると、そのインスタンス内のすべてのデータベースが削除されます。 インスタンスが削除されると元に戻せません。