gcloud CLI を使用してデータベースを作成してクエリを実行する

目標

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

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

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

料金

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

準備

  1. gcloud CLI のインストールと Cloud Spanner API の設定に記載された手順を完了します。この手順では、デフォルトの Google Cloud プロジェクトの作成と設定、課金の有効化、Cloud Spanner APIの有効化、OAuth 2.0 を設定し Cloud Spanner API を使用するための認証情報を取得する方法について説明します。

特に、ローカル開発環境で認証情報を設定するために、必ず gcloud auth application-default login を実行してください。

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

まだ設定していない場合は、Google Cloud プロジェクトの ID を Google Cloud CLI のデフォルト プロジェクトとして設定します。

gcloud config set project PROJECT_ID

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

gcloud spanner --project=PROJECT_ID instance-configs list

インスタンス

Spanner を最初に使用する場合は、インスタンスを作成する必要があります。インスタンスとは、Spanner データベースによって使用されるリソースの割り当てのことです。インスタンスの作成時には、データの保存場所とインスタンスの持つコンピューティング容量を選択します。

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

インスタンスを作成するにはインスタンス構成を選択する必要があります。この構成は 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 プロジェクト内で一意である必要があります。

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

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

gcloud config set spanner/instance test-instance

データベースの作成

example-db という名前のデータベースを作成します。 データベース言語はデフォルトで GoogleSQL になります。

GoogleSQL

gcloud spanner databases create example-db

PostgreSQL

gcloud spanner databases create example-db --database-dialect=POSTGRESQL

スキーマを更新する

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

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

GoogleSQL

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'

PostgreSQL

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId bigint NOT NULL, FirstName varchar(1024), LastName varchar(1024), SingerInfo bytea, PRIMARY KEY (SingerId) )'

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId bigint NOT NULL, AlbumId bigint NOT NULL, AlbumTitle varchar, PRIMARY KEY (SingerId, AlbumId) ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

オペレーションの進行状況を確認するには、gcloud spanner operations describe を使用します。 このコマンドにはオペレーション ID が必要です。

オペレーション ID を取得します。

gcloud spanner operations list --instance="test-instance" \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

DATABASE-NAME は、データベースの名前に置き換えます。

gcloud spanner operations describe を実行します。

gcloud spanner operations describe \
  --instance="test-instance" \
  --database="example-db" \
  projects/PROJECT-NAME/instances/test-instance/databases/example-db/operations/OPERATION-ID

以下を置き換えます。

  • PROJECT-NAME: プロジェクト名。
  • OPERATION-ID: 確認するオペレーションのオペレーション ID。

出力は次のようになります。

done: true
metadata:
...
progress:
- endTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
  startTime: '2022-03-01T00:28:04.221401Z'
- endTime: '2022-03-01T00:28:17.624588Z'
  startTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
...

データを書き込む

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

GoogleSQL

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"

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

PostgreSQL

gcloud spanner databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')"

gcloud spanner databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 2, 'Go, Go, Go')"

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

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

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

Spanner SQL リファレンスについては、Google SQL のクエリ構文または PostgreSQL のクエリ構文をご覧ください。

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

クリーンアップ

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

データベースの削除

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

gcloud spanner databases delete example-db

インスタンスの削除

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

gcloud spanner instances delete test-instance

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