使用 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 instance-configs list

執行個體

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

執行個體和執行個體設定

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

清單執行個體設定

建立執行個體時，您會指定「執行個體設定」，定義該執行個體中資料庫的地理位置和複製功能。您可以選擇地區設定，將資料儲存在一個地區；也可以選擇雙區域設定，將資料儲存在同一個國家/地區的兩個區域；或者選擇多區域設定，將資料分散到多個區域。詳情請參閱「執行個體總覽」。

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

gcloud instance-configs list

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

建立執行個體

使用具有 1 個節點的地區執行個體設定 regional-us-central1，建立名稱為 test-instance 且顯示名稱為 My 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) 建立、變更或刪除資料表，以及建立或刪除索引。

我們來建立兩個資料表：

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

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

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取您在本教學課程中所用資源的相關費用，請捨棄資料庫並刪除您建立的執行個體。

捨棄資料庫

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

gcloud databases delete example-db

刪除執行個體

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

gcloud instances delete test-instance

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