目标
本教程将介绍如何使用 Spanner 完成以下步骤: 客户端库:
- 创建 Spanner 实例和数据库。
- 写入、读取数据库中的数据和对数据执行 SQL 查询。
- 更新数据库架构。
- 使用读写事务更新数据。
- 向数据库添加二级索引。
- 使用索引来读取数据和对数据执行 SQL 查询。
- 使用只读事务检索数据。
费用
本教程使用 Spanner,它是 Google Cloud 的收费组件。如需了解 Spanner 的使用费用,请参阅价格。
准备工作
完成设置中介绍的步骤,包括创建和设置默认 Google Cloud 项目、启用结算功能、启用 Cloud Spanner API 以及设置 OAuth 2.0 来获取身份验证凭据以使用 Cloud Spanner API。
尤其要确保运行 gcloud auth
application-default login
,以便使用身份验证凭据设置本地开发环境。
准备本地 Ruby 环境
在开发机器上安装以下内容(如果尚未安装):
将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples
或者,也可以下载该示例的 zip 文件并将其解压缩。
切换到包含 Spanner 示例代码的目录:
cd ruby-docs-samples/spanner/
安装依赖项:
bundle install
将 GOOGLE_CLOUD_PROJECT 环境变量设置为您的 Google Cloud 项目 ID:
export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]
创建实例
首次使用 Spanner 时,您必须创建一个实例,实例是 Spanner 数据库使用的资源分配单位。创建实例时,请选择一个实例配置(决定数据的存储位置),同时选择要使用的节点数(决定实例中服务资源和存储资源的数量)。
执行以下命令,在区域 us-central1
中创建具有 1 个节点的 Spanner 实例:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
请注意,此命令将创建一个具有以下特征的实例:
- 实例 ID 为
test-instance
- 显示名为
Test Instance
- 实例配置为
regional-us-central1
(单区域配置将数据存储在单个区域中,而多区域配置则将数据分布在多个区域中。如需了解详情,请参阅实例简介。) - 节点数为 1(
node_count
对应于实例中数据库可用的服务资源和存储资源的数量。有关详情,请参阅节点和 处理单元)。
您应该会看到:
Creating instance...done.
浏览示例文件
示例代码库包含一个示例,展示了如何在 Ruby 中使用 Spanner。
请浏览spanner_samples.rb
文件,其中说明了如何使用 Spanner。代码展示了如何创建和使用新数据库。数据
使用
架构和数据模型页面。
创建数据库
通过在命令行运行以下命令,在名为 test-instance
的实例中创建名为 example-db
的数据库。
bundle exec ruby spanner_samples.rb create_database test-instance example-db
您应该会看到:
Created database example-db on instance test-instance
下一步是将数据写入数据库。
创建数据库客户端
您必须先创建一个Client
,然后才能执行读写操作。您
可以将 Client
视为数据库连接:您与
Spanner 必须通过 Client
。通常,您可以在应用启动时创建 Client
,然后重复使用该 Client
来读取、写入和执行事务。以下代码演示了如何创建客户端。
如需了解详情,请参阅 Client
参考文档。
使用 DML 写入数据
您可以在读写事务中使用数据操纵语言 (DML) 插入数据。
使用 execute_update()
方法来执行 DML 语句。
使用 write_using_dml
参数运行示例。
bundle exec ruby spanner_samples.rb write_using_dml test-instance example-db
您应该会看到:
4 records inserted.
使用变更写入数据
您还可以使用变更插入数据。
您可以使用 Client
对象来写入数据。Client#commit
方法跨数据库中的列、行和表,为在单个逻辑时间点以原子方式执行的写入创建并提交事务。
此代码演示了如何使用变更写入数据:
使用 insert_data
参数运行示例。
bundle exec ruby spanner_samples.rb insert_data test-instance example-db
您应该会看到:
Inserted data
使用 SQL 查询数据
Spanner 支持使用 SQL 接口读取数据, 使用 Google Cloud CLI 或 以编程方式使用 适用于 Ruby 的 Spanner 客户端库。
在命令行中
执行以下 SQL 语句,读取 Albums
表中所有列的值:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
结果应为:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
使用适用于 Ruby 的 Spanner 客户端库
除了在命令行上执行 SQL 语句外,还可以发出 使用 Spanner 客户端库以编程方式创建相同的 SQL 语句 Ruby。
使用 Client#execute
方法运行 SQL 查询。使用 Ruby 符号 :ColumnName
可访问某一行特定列的数据。
下面演示了如何发出查询并访问数据:
使用 query_data
参数运行示例。
bundle exec ruby spanner_samples.rb query_data test-instance example-db
您应该会看到以下结果:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
使用 SQL 参数进行查询
如果您的应用具有频繁执行的查询,您可以提高其性能 对其进行参数化处理。生成的参数查询可以缓存下来并重复使用,这样做可以降低编译开销。如需了解详情,请参阅 使用查询参数加快频繁执行的查询的速度。
以下示例演示了如何在 WHERE
子句中使用参数来查询包含特定 LastName
值的记录。
使用 query_with_parameter 参数运行示例。
bundle exec ruby spanner_samples.rb query_with_parameter test-instance example-db
您应该会看到以下结果:
12 Melissa Garcia
使用读取 API 读取数据
除了 Spanner 的 SQL 接口之外,Spanner 还支持 读取接口。
使用 Client
类的 Client#read
方法从数据库中读取行。
下面演示了如何读取数据:
使用 read_data
参数运行示例。
bundle exec ruby spanner_samples.rb read_data test-instance example-db
您看到的输出结果应该类似于以下内容:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
更新数据库架构
假设您需要将名为 MarketingBudget
的新列添加到 Albums
表。向现有表添加新列需要更新数据库架构。Spanner 支持在数据库继续处理流量的同时,对数据库进行架构更新。架构更新不需要使数据库离线,并且不会锁定整个表或列;在架构更新期间,您可以继续将数据写入数据库。详细了解“支持”
架构更新和架构更改性能,
进行架构更新。
添加列
您可以使用 Google Cloud CLI 或 以编程方式使用 适用于 Ruby 的 Spanner 客户端库。
在命令行中
使用以下 ALTER TABLE
命令向表添加新列:
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'
您应该会看到:
Schema updating...done.
使用 Ruby 版 Spanner 客户端库
使用Database
类的 Database#update
方法来修改架构:
使用 add_column
参数运行示例。
bundle exec ruby spanner_samples.rb add_column test-instance example-db
您应该会看到:
Added the MarketingBudget column
将数据写入新列
以下代码可将数据写入新列。对于 Albums(1, 1)
键控的行,该代码会将 MarketingBudget
设置为 100000
;而对于 Albums(2, 2)
键控的行,该代码会将其设置为 500000
。
使用 update_data
参数运行示例。
bundle exec ruby spanner_samples.rb update_data test-instance example-db
您应该会看到:
Updated data
您还可以执行 SQL 查询或读取调用来获取刚才写入的值。
以下是执行查询的代码:
如需执行此查询,请使用 query_data_with_new_column
参数运行示例。
bundle exec ruby spanner_samples.rb query_data_with_new_column test-instance example-db
您应该会看到:
1 1 100000
1 2
2 1
2 2 500000
2 3
更新数据
您可以在读写事务中使用 DML 来更新数据。
使用 execute_update()
方法来执行 DML 语句。
使用 write_with_transaction_using_dml
参数运行示例。
bundle exec ruby spanner_samples.rb write_with_transaction_using_dml test-instance example-db
您应该会看到:
Transaction complete
使用二级索引
假设您想要提取 Albums
表中 AlbumTitle
值在特定范围内的所有行。您可以使用 SQL 语句或读取调用读取 AlbumTitle
列中的所有值,然后舍弃不符合条件的行。不过,执行全表扫描费用高昂,特别是对内含大量行的表来说更是如此。相反,如果对表创建二级索引,按非主键列进行搜索,则可以提高行检索速度。
向现有表添加二级索引需要更新架构。点赞 Spanner 支持添加索引,同时 以便继续处理流量Spanner 会自动回填 使用现有数据创建索引。回填可能需要几分钟时间才能完成,但在此过程中,您无需使数据库离线,也无需避免写入已编入索引的表。如需了解详情,请参阅添加二级索引。
添加二级索引后,Spanner 会自动使用该索引进行 SQL 查询,使用该索引后,查询运行速度可能会提高。如果使用读取接口,则必须指定要使用的索引。
添加二级索引
您可以使用 gcloud CLI 在命令行中添加索引,也可以使用 Ruby 版 Spanner 客户端库以编程方式添加索引。
在命令行中
使用以下 CREATE INDEX
命令向数据库添加索引:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
您应该会看到:
Schema updating...done.
使用 Ruby 版 Spanner 客户端库
使用 Database
类的 Database#update
方法来添加索引:
使用 create_index
参数运行示例。
bundle exec ruby spanner_samples.rb create_index test-instance example-db
添加索引可能需要几分钟时间。添加索引后,您应该会看到:
Added the AlbumsByAlbumTitle index
使用索引进行读取
对于 SQL 查询,Spanner 会自动使用适当的索引。在读取接口中,您必须在请求中指定索引。
如需在读取接口中使用索引,请向 Client
类的 read
方法提供 index
参数。
使用 read_data_with_index
参数运行示例。
bundle exec ruby spanner_samples.rb read_data_with_index test-instance example-db
您应该会看到:
2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk
为仅索引读取添加索引
您可能已经注意到,上一个读取示例不包括读取 MarketingBudget
列。这是因为 Spanner 的读取接口
不支持将索引与数据表联接以查找值的功能
未存储在索引中的数据。
请创建 AlbumsByAlbumTitle
的备用定义,用于将 MarketingBudget
的副本存储到索引中。
在命令行中
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
添加索引可能需要几分钟时间。添加索引后,您应该会看到:
Schema updating...done.
使用 Ruby 版 Spanner 客户端库
使用Database#update
Database
的
类来添加带有 STORING
子句的索引:
使用 create_storing_index
参数运行示例。
bundle exec ruby spanner_samples.rb create_storing_index test-instance example-db
您应该会看到:
Added the AlbumsByAlbumTitle2 index
现在,当您执行读取操作时便可从 AlbumsByAlbumTitle2
索引中提取所有 AlbumId
、AlbumTitle
和 MarketingBudget
列:
使用 read_data_with_storing_index
参数运行示例。
bundle exec ruby spanner_samples.rb read_data_with_storing_index test-instance example-db
您看到的输出结果应该类似于以下内容:
2 Forever Hold Your Peace 300000
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk 300000
使用只读事务检索数据
假设您要在同一时间戳执行多个读取操作。只读事务会遵从一致的事务提交历史记录前缀,因此您的应用始终可获得一致的数据。
使用 Snapshot
对象执行只读事务。使用 Client
类的 snapshot
方法来获取 Snapshot
对象。
下面演示了如何运行查询并在同一只读事务中执行读取操作:
使用 read_only_transaction
参数运行示例。
bundle exec ruby spanner_samples.rb read_only_transaction test-instance example-db
您看到的输出结果应该类似于以下内容:
2 Forever Hold Your Peace 2
2 Go, Go, Go 1
1 Green 2
3 Terrified 2
1 Total Junk 1
1 Total Junk 1
2 Go, Go, Go 1
1 Green 2
2 Forever Hold Your Peace 2
3 Terrified 2
清理
为避免因本教程中使用的资源导致您的 Google Cloud 账号产生额外费用,请删除数据库和您创建的实例。
删除数据库
如果您删除一个实例,则该实例中的所有数据库都会自动删除。 本步骤演示了如何在不删除实例的情况下删除数据库(您仍需为该实例付费)。
在命令行中
gcloud spanner databases delete example-db --instance=test-instance
使用 Google Cloud 控制台
前往 Google Cloud 控制台中的 Spanner 实例页面。
点击实例。
点击您想删除的数据库。
在数据库详细信息页面中,点击删除。
确认您要删除数据库并点击删除。
删除实例
删除实例会自动删除在该实例中创建的所有数据库。
在命令行中
gcloud spanner instances delete test-instance
使用 Google Cloud 控制台
前往 Google Cloud 控制台中的 Spanner 实例页面。
点击您的实例。
点击删除。
确认您要删除实例并点击删除。
后续步骤
了解如何通过虚拟机实例访问 Spanner。
如需了解授权和身份验证凭据,请参阅使用客户端库向 Cloud 服务进行身份验证。
详细了解 Spanner 架构设计最佳实践。