使用 Google Cloud CLI 建立及查詢資料庫

目標

本教學課程將引導您使用 gcloud CLI 完成下列步驟：

  • 建立 Spanner 執行個體、資料庫和結構定義
  • 將資料寫入資料庫，並對資料執行 SQL 查詢
  • 刪除資料庫和執行個體來清除所用資源

本頁面的程序適用於 GoogleSQL 方言資料庫和 PostgreSQL 方言資料庫。

如需完整的 Spanner gcloud 參考資料，請參閱 gcloud。

定價

本教學課程使用 Spanner，這是Google Cloud的計費元件。如要瞭解 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

如未設定預設專案，則必須將 --project PROJECT_ID 傳遞至下列各指令，做為 gcloud 的第一個引數。例如：

gcloud --project=PROJECT_ID spanner instance-configs list

執行個體

首次使用 Spanner 時，必須建立執行個體，也就是 Spanner 資料庫所用的資源分配單位。建立執行個體時，您必須選擇資料儲存位置，以及執行個體的運算能力。

執行個體和執行個體設定

如要建立執行個體，您必須選取執行個體設定，這就像是執行個體的藍圖，定義了 Spanner 資料的地理位置和複製作業。

清單執行個體設定

建立執行個體時，您必須指定執行個體設定，定義該執行個體中資料庫的地理位置和複製作業。您可以選擇單區域設定 (將資料儲存在一個區域)、雙區域設定 (將資料儲存在同一國家/地區的兩個區域)，或多區域設定 (將資料分散儲存在多個區域)。詳情請參閱「執行個體總覽」。

如要查看專案可用的一組執行個體設定：

gcloud spanner instance-configs list

您應該會看到單區域、雙區域和多區域設定的清單。

建立執行個體

如要使用區域性執行個體設定 regional-us-central1 建立名為 test-instance 的執行個體，並將顯示名稱設為 My Instance，且節點數量為 1，請執行下列指令：

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

在上述指令中，執行個體名稱設為 test-instance，--description 則設定執行個體的顯示名稱。這兩個值在 Google Cloud 專案中不得重複。

設定預設執行個體

您可以設定 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) 建立、變更或刪除資料表，以及建立或刪除索引。

現在來建立兩個資料表：

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 參考資料，請參閱「GoogleSQL 的查詢語法」或「PostgreSQL 的查詢語法」。

如要查看可與 execute-sql 指令搭配使用的旗標清單，請參閱「gcloud spanner databases execute-sql」。

清除所用資源

為避免系統向您的 Google Cloud 帳戶收取額外費用，請刪除資料庫和執行個體。停用 Cloud Billing API 並不會停止計費。刪除執行個體時，當中的所有資料庫都會刪除。

捨棄資料庫

如要刪除現有的執行個體：

gcloud spanner databases delete example-db

刪除執行個體

如要刪除現有的執行個體：

gcloud spanner instances delete test-instance

請注意，刪除執行個體也會一併捨棄該執行個體中的所有資料庫。刪除執行個體後即無法復原。