目標
このチュートリアルでは、gcloud CLI を使用して次の手順について説明します。
- Spanner のインスタンス、データベース、スキーマを作成する
- データベースにデータを書き込み、そのデータに対して SQL クエリを実行する
- データベースとインスタンスを削除してクリーンアップする
このページの手順は、GoogleSQL 言語データベースと PostgreSQL 言語データベースの両方に適用されます。
Spanner gcloud の完全なリファレンスについては、gcloud をご覧ください。
料金
このチュートリアルでは、Google Cloudの課金対象コンポーネントである Spanner を使用します。Spanner の使用料金については、料金についてのページをご覧ください。
始める前に
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 の最初の引数として --project
PROJECT_ID を渡す必要があります。例:
gcloud --project=PROJECT_ID instance-configs list
インスタンス
Spanner を最初に使用する際は、インスタンスを作成する必要があります。インスタンスとは、Spanner データベースによって使用されるリソースの割り当てのことです。インスタンスの作成時には、データの保存場所とインスタンスの持つコンピューティング容量を選択します。
インスタンスとインスタンス構成
インスタンスを作成するにはインスタンス構成を選択する必要があります。この構成は Spanner データの地理的配置とレプリケーションを定義するインスタンスの設計図のようなものです。
インスタンス設定を一覧表示する
インスタンスの作成時には「インスタンス構成」を指定し、そのインスタンスのデータベースの地理的位置とレプリケーションを定義します。1 つのリージョンにデータを格納するリージョン構成、同じ国の 2 つのリージョンにデータを格納するデュアルリージョン、または複数のリージョンにデータを分散するマルチリージョン構成を選択できます。詳細については、インスタンスの概要をご覧ください。
プロジェクトで使用可能なインスタンス構成の一覧を表示するには、次のコマンドを実行します。
gcloud instance-configs list
リージョン、デュアルリージョン、マルチリージョンの構成のリストが表示されます。
インスタンスを作成する
1 ノードのリージョン インスタンス設定 regional-us-central1 を使用して、表示名 My Instance を持つ test-instance という名前のインスタンスを作成する場合は、以下の操作を実行します。
gcloud 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 databases create example-db
PostgreSQL
gcloud databases create example-db --database-dialect=POSTGRESQL
スキーマを更新する
Spanner の データ定義言語（DDL）はテーブルの作成、変更、削除、またはインデックスの作成や削除に使用されます。
2 つのテーブルを作成してみましょう
GoogleSQL
gcloud 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 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 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 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 operations describe を使用します。
このコマンドにはオペレーション ID が必要です。
オペレーション ID を取得します。
gcloud operations list --instance="test-instance" \ --database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
DATABASE-NAME は、データベースの名前に置き換えます。
gcloud operations describe を実行します。
gcloud 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 rows insert --database=example-db \ --table=Singers \ --data=SingerId=1,FirstName=Marc,LastName=Richards gcloud rows insert --database=example-db \ --table=Singers \ --data=SingerId=2,FirstName=Catalina,LastName=Smith gcloud rows insert --database=example-db \ --table=Singers \ --data=SingerId=3,FirstName=Alice,LastName=Trentor gcloud rows insert --database=example-db \ --table=Albums \ --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk" gcloud rows insert --database=example-db \ --table=Albums \ --data=SingerId=2,AlbumId=1,AlbumTitle="Green" gcloud rows insert --database=example-db \ --table=Albums \ --data=^:^SingerId=2:AlbumId=2:AlbumTitle="Go, Go, Go"
デフォルトでは、リスト内のアイテムはカンマで区切ります。最後の挿入コマンドでは、区切り文字としてコロン（^:^）を指定したため、アルバムのタイトルにカンマを使用できました。
PostgreSQL
gcloud databases execute-sql example-db \ --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')" gcloud databases execute-sql example-db \ --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')" gcloud databases execute-sql example-db \ --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')" gcloud databases execute-sql example-db \ --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')" gcloud databases execute-sql example-db \ --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')" gcloud databases execute-sql example-db \ --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 2, 'Go, Go, Go')"
SQL を使用してデータをクエリする
コマンドラインでクエリを実行します。
gcloud databases execute-sql example-db \ --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
Spanner SQL リファレンスについては、Google SQL のクエリ構文または PostgreSQL のクエリ構文をご覧ください。
execute-sql コマンドで使用できるフラグのリストについては、gcloud データベースの exit-sql をご覧ください。
クリーンアップ
このチュートリアルで使用したリソースについて Google Cloud アカウントに課金されないようにするには、作成したデータベースとインスタンスを削除します。
データベースを削除する
既存のインスタンスを削除するには、次のコマンドを実行します。
gcloud databases delete example-db
インスタンスを削除する
既存のインスタンスを削除するには、次のコマンドを実行します。
gcloud instances delete test-instance
インスタンスを削除すると、そのインスタンス内のすべてのデータベースが削除されます。インスタンスが削除されると元に戻せません。