Cloud Spanner 使用入门 (gcloud)

目标

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

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

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

费用

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

准备工作

完成设置中介绍的步骤，包括创建和设置默认 Google Cloud 项目、启用结算功能、启用 Cloud Spanner API 以及设置 OAuth 2.0 以获取使用 Cloud Spanner API 所需的身份验证凭据。
特别注意，请务必运行 gcloud auth application-default login，以便使用身份验证凭据设置本地开发环境。

设置默认项目

如果您尚未设置默认项目，请将 Google Cloud Platform 项目的 ID 设置为 gcloud 命令行工具的默认项目：

gcloud config set project PROJECT_ID

如果未设置默认项目，则必须将下面每个命令的 --project PROJECT_ID 作为第一个参数传递给 gcloud spanner。例如：

gcloud spanner --project=PROJECT_ID instance-configs list

实例

在首次使用 Cloud Spanner 时，必须创建一个实例，用于分配供 Cloud Spanner 数据库使用的资源。创建实例时，您可以选择数据的存储位置以及数据使用的节点数量。

实例和实例配置

要创建实例，您必须选择一个实例配置，它就像是您的实例蓝图，其定义 Cloud 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 的数据库。

gcloud spanner databases create example-db

创建架构

使用 Cloud Spanner 的数据定义语言 (DDL) 来创建、修改或删除表，以及创建或删除索引。

我们来创建两个表

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'

写入数据

让我们向数据库中添加一些示例数据

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"

默认情况下，使用逗号分隔列表中的项。在最后一个插入命令中，我们用冒号 (^:^) 作为分隔符，以便在专辑标题中使用英文逗号。

使用 SQL 查询数据

对命令行执行查询：

gcloud spanner databases execute-sql example-db \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

如需查看 Cloud Spanner SQL 参考，请参阅查询语法。

要查看可与 execute-sql 命令配合使用的标志列表，请参阅 gcloud spanner databases execute-sql。

清理

为避免因本教程中使用的资源导致您的 Google Cloud 帐号产生额外费用，请删除数据库和您创建的实例。

删除数据库

要删除现有实例，请输入以下命令：

gcloud spanner databases delete example-db

删除实例

要删除现有实例，请输入以下命令：

gcloud spanner instances delete test-instance

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