使用 gcloud CLI 创建和查询数据库

目标

本教程将介绍如何使用 gcloud 命令行工具完成以下步骤。

  • 创建 Spanner 实例、数据库和架构
  • 将数据写入数据库并对该数据执行 SQL 查询
  • 通过删除数据库和实例进行清理

如需查看完整的 gcloud spanner 参考,请参阅 gcloud spanner

价格

本教程使用 Spanner,它是 Google Cloud 的收费组件。如需了解 Spanner 的使用费用,请参阅价格

准备工作

  1. 完成设置中介绍的步骤,包括创建和设置默认 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 spanner。例如:

gcloud spanner --project=PROJECT_ID 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 项目中都必须是唯一的。

设置默认实例

您可以设置当您的命令中未指定实例时 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 账号产生额外费用,请删除数据库和您创建的实例。

删除数据库

要删除现有实例,请输入以下命令:

gcloud spanner databases delete example-db

删除实例

要删除现有实例,请输入以下命令:

gcloud spanner instances delete test-instance

请注意,删除实例也会移除该实例中的所有数据库。 删除实例是不可逆转的。