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

目标

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

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

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

价格

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

准备工作

  1. 完成 安装 gcloud CLI 并设置 Cloud Spanner API。 其中介绍了如何创建和设置默认 Google Cloud 项目, 启用 Cloud Spanner API 并设置 OAuth 2.0,以获取 身份验证凭据才能使用 Cloud Spanner API。

尤其要注意,请务必运行 gcloud auth application-default login,以便使用身份验证凭据设置本地开发环境。

设置默认项目

将 Google Cloud 项目的 ID 设置为默认值(如果您尚未执行此操作) 项目:

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 项目中都必须是唯一的。

设置默认实例

您可以设置 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

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