目标
本教程将介绍如何使用 Spanner 完成以下步骤: 适用于 PHP 的客户端库:
- 创建 Spanner 实例和数据库。
- 写入、读取数据库中的数据和对数据执行 SQL 查询。
- 更新数据库架构。
- 使用读写事务更新数据。
- 向数据库添加二级索引。
- 使用索引来读取数据和对数据执行 SQL 查询。
- 使用只读事务检索数据。
费用
本教程使用 Spanner,它是 Google Cloud如需了解 Spanner 的使用费用,请参阅 定价。
准备工作
完成设置中介绍的步骤,包括创建和设置默认 Google Cloud 项目、启用结算功能、启用 Cloud Spanner API 以及设置 OAuth 2.0 来获取身份验证凭据以使用 Cloud Spanner API。
尤其要确保运行 gcloud auth
application-default login
,以便使用身份验证凭据设置本地开发环境。
准备本地 PHP 环境
按照服务账号中的步骤将一个服务账号设置为您的应用默认凭据。已关注 您应该同时获得服务账号密钥文件(采用 JSON 格式)和
GOOGLE_APPLICATION_CREDENTIALS
环境变量, 向 Spanner API 进行身份验证。在开发机器上安装以下内容(如果尚未安装):
将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
或者,也可以下载该示例的 zip 文件并将其解压缩。
切换到包含 Spanner 示例代码的目录:
cd php-docs-samples/spanner
安装依赖项:
composer install
这将安装适用于 PHP 的 Spanner 客户端库, 可通过运行
composer require google/cloud-spanner
添加到任何项目。
创建实例
首次使用 Spanner 时,您必须创建一个实例, 分配 Spanner 数据库使用的资源。创建实例时,请选择一个实例配置(决定数据的存储位置),同时选择要使用的节点数(决定实例中服务资源和存储资源的数量)。
执行以下命令,在该区域中创建 Spanner 实例
us-central1
,具有 1 个节点:
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.
浏览示例文件
示例代码库包含一个示例,展示了如何使用 Spanner 使用 PHP。
请查看 src/create_database.php
和 src/add_column.php
中的函数,它们展示了如何创建数据库和修改数据库架构。数据使用架构和数据模型页面中显示的示例架构。
创建数据库
通过以下方法在名为 test-instance
的实例中创建名为 example-db
的数据库:
请在命令行中运行以下命令。
php src/create_database.php test-instance example-db
您应该会看到:
Created database example-db on instance test-instance
下一步是将数据写入数据库。
创建数据库客户端
如需执行读写操作,您需要获取Google\Cloud\Spanner\Database
的实例。
您可以将 Database
视为数据库连接:您的所有互动
必须通过 Database
进行检查。通常,您可以在应用启动时创建 Database
,然后重复使用该 Database
来读取、写入和执行事务。每个客户端均使用 Spanner 中的资源。
如果您在同一应用中创建多个客户端,则应调用 Database::close
来清理客户端的资源,包括网络连接(一旦不再需要这些资源就立即清理)。
如需了解详情,请参阅 Database
参考文档。
使用 DML 写入数据
您可以在读写事务中使用数据操纵语言 (DML) 插入数据。
使用 executeUpdate()
方法来执行 DML 语句。
运行示例文件 src/write_data_with_dml.php
。
php src/write_data_with_dml.php test-instance example-db
您应该会看到:
Inserted 4 row(s).
使用变更写入数据
您还可以使用变更插入数据。
您可以使用 Database::insertBatch
方法来写入数据。insertBatch
会向表中添加新行。单个批处理中的所有插入均以原子方式应用。
此代码演示了如何使用变更写入数据:
运行示例文件 src/insert_data.php
。
php src/insert_data.php test-instance example-db
您应该会看到:
Inserted data.
使用 SQL 查询数据
Spanner 支持使用 SQL 接口读取数据, 使用 Google Cloud CLI 或 以编程方式使用 适用于 PHP 的 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
使用适用于 PHP 的 Spanner 客户端库
除了在命令行上执行 SQL 语句外,还可以发出 使用 Spanner 客户端库以编程方式创建相同的 SQL 语句 。
使用Database::execute()
运行 SQL 查询。
下面演示了如何发出查询并访问数据:
运行示例文件 src/query_data.php
。
php src/query_data.php test-instance example-db
您应该会看到以下结果:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
您的结果不一定会按此顺序排列。如果您需要确保
请使用 ORDER BY
子句,如
SQL 最佳实践。
使用 SQL 参数进行查询
如果您的应用具有频繁执行的查询,您可以提高其性能 对其进行参数化处理。生成的参数查询可以缓存和重复使用 降低编译开销。如需了解详情,请参阅 使用查询参数加快频繁执行的查询的速度。
以下示例展示了如何在 WHERE
子句中使用形参
包含特定 LastName
值的查询记录。
运行示例文件 src/query_data_with_parameter.php
。
php src/query_data_with_parameter.php test-instance example-db
您应该会看到以下结果:
SingerId: 12, FirstName: Melissa, LastName: Garcia
使用读取 API 读取数据
除了 Spanner 的 SQL 接口之外,Spanner 还支持 读取接口。
使用 Database::read()
从数据库中读取行。使用 KeySet
对象定义要读取的键和键范围的集合。
下面演示了如何读取数据:
运行 read_data.php
文件中的示例。
php read_data.php test-instance example-db
您看到的输出结果应该类似于以下内容:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
更新数据库架构
假设您需要将名为 MarketingBudget
的新列添加到 Albums
表。向现有表添加新列需要更新数据库架构。Spanner 支持对数据库进行架构更新,同时
以便继续处理流量架构更新不需要
数据库离线,且不会锁定整个表或列;您可以继续
在架构更新期间将数据写入数据库。详细了解“支持”
架构更新和架构更改性能,
进行架构更新。
添加列
您可以使用 Google Cloud CLI 或 以编程方式使用 适用于 PHP 的 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.
使用适用于 PHP 的 Spanner 客户端库
使用 Database::updateDdl
修改架构:
运行示例文件 src/add_column.php
。
php src/add_column.php test-instance example-db
您应该会看到:
Added the MarketingBudget column.
将数据写入新列
以下代码可将数据写入新列。对于 Albums(1, 1)
键控的行,该代码会将 MarketingBudget
设置为 100000
;而对于 Albums(2, 2)
键控的行,该代码会将其设置为 500000
。
运行示例文件 src/update_data.php
。
php src/update_data.php test-instance example-db
您应该会看到:
Updated data.
您还可以执行 SQL 查询或读取调用来获取刚才写入的值。
以下是执行查询的代码:
如需执行此查询,请运行示例文件 src/query-data-with-new-column.php
。
php src/query_data_with_new_column.php test-instance example-db
您应该会看到:
SingerId: 1, AlbumId: 1, MarketingBudget: 100000
SingerId: 1, AlbumId: 2, MarketingBudget: 0
SingerId: 2, AlbumId: 1, MarketingBudget: 0
SingerId: 2, AlbumId: 2, MarketingBudget: 500000
SingerId: 2, AlbumId: 3, MarketingBudget: 0
更新数据
您可以在读写事务中使用 DML 来更新数据。
使用 executeUpdate()
方法来执行 DML 语句。
运行示例文件 src/write_data_with_dml_transaction.php
。
php src/write_data_with_dml_transaction.php test-instance example-db
您应该会看到:
Transaction complete.
使用二级索引
假设您想要提取 Albums
表中 AlbumTitle
值在特定范围内的所有行。您可以使用 SQL 语句或读取调用读取 AlbumTitle
列中的所有值,然后舍弃不符合条件的行。不过,执行全表扫描费用高昂,特别是对内含大量行的表来说更是如此。相反,如果对表创建二级索引,按非主键列进行搜索,则可以提高行检索速度。
向现有表添加二级索引需要更新架构。点赞 Spanner 支持添加索引,同时 以便继续处理流量Spanner 会自动回填 使用现有数据创建索引。回填可能需要几分钟时间才能完成,但在此过程中,您无需使数据库离线,也无需避免写入已编入索引的表。有关详情,请参阅 添加二级索引。
添加二级索引后,Spanner 会自动将其用于 使用索引可能会提高运行速度的 SQL 查询。如果使用读取接口,则必须指定要使用的索引。
添加二级索引
您可以使用 gcloud CLI 或 以编程方式使用 PHP 版 Spanner 客户端库。
在命令行中
使用以下 CREATE INDEX
命令向数据库添加索引:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
您应该会看到:
Schema updating...done.
使用适用于 PHP 的 Spanner 客户端库
使用 Database::updateDdl
添加索引:
运行示例文件 src/create_index.php
。
php src/create_index.php test-instance example-db
添加索引可能需要几分钟时间。添加索引后,您应该会看到:
Added the AlbumsByAlbumTitle index.
使用索引进行读取
对于 SQL 查询,Spanner 会自动使用适当的索引。在读取接口中,您必须在请求中指定索引。
要在读取接口中使用索引,请使用 Database::read
方法。
运行示例文件 src/read_data_with_index.php
。
php src/read_data_with_index.php test-instance example-db
您应该会看到:
AlbumId: 2, AlbumTitle: Forever Hold your Peace
AlbumId: 2, AlbumTitle: Go, Go, Go
AlbumId: 1, AlbumTitle: Green
AlbumId: 3, AlbumTitle: Terrified
AlbumId: 1, AlbumTitle: 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.
使用适用于 PHP 的 Spanner 客户端库
使用Database::updateDdl
添加带 STORING
子句的索引:
运行示例文件 src/create_storing_index.php
。
php src/create_storing_index.php test-instance example-db
您应该会看到:
Added the AlbumsByAlbumTitle2 index.
现在,当您执行读取操作时便可从 AlbumsByAlbumTitle2
索引中提取所有 AlbumId
、AlbumTitle
和 MarketingBudget
列:
运行示例文件 src/read_data_with_storing_index.php
。
php src/read_data_with_storing_index.php test-instance example-db
您看到的输出结果应该类似于以下内容:
AlbumId: 2, AlbumTitle: Forever Hold your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Green, MarketingBudget: 0
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Total Junk, MarketingBudget: 300000
使用只读事务检索数据
假设您要在同一时间戳执行多个读取操作。只读
事务会观察到一致的
事务提交历史记录的前缀,以便您的应用始终
一致的数据
使用 Snapshot
对象执行只读事务。使用 Database::snapshot
方法来获取 Snapshot
对象。
下面演示了如何运行查询并在同一只读事务中执行读取操作:
运行示例文件 src/read_only_transaction.php
。
php src/read_only_transaction.php test-instance example-db
您看到的输出结果应该类似于以下内容:
Results from first read:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Results from second read:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
清理
为避免因本教程中使用的资源导致您的 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 架构设计最佳实践。