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

目標

本教學課程將逐步引導您使用 gcloud CLI 執行下列步驟：

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

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

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

注意： 如要使用 90 天免費試用執行個體探索 Spanner，請參閱「建立 Spanner 免費試用執行個體」。

定價

本教學課程使用 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

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

建立執行個體

使用具有 1 個節點的地區執行個體設定 regional-us-central1，建立名稱為 test-instance 且顯示名稱為 My Instance 的執行個體：

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

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

注意： 在 gcloud 指令中參照執行個體時，請使用執行個體 ID，而非顯示名稱。

設定預設執行個體

當您尚未在指令中指定執行個體時，您可以設定 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

注意： 已知問題：使用突變將資料寫入 PostgreSQL 資料庫時，gcloud CLI 無法查閱資料表名稱。因此，您必須使用 DML 插入資料。

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 帳戶收取您在本教學課程中所用資源的相關費用，請捨棄資料庫並刪除您建立的執行個體。

捨棄資料庫

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

gcloud spanner databases delete example-db

刪除執行個體

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

gcloud spanner instances delete test-instance

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