目标
本教程将引导您使用 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
请注意,删除实例也会移除该实例中的所有数据库。 删除实例是不可逆转的。