spanner-basics 技能深度解析Google Cloud Spanner 全栈运维与开发实战指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本指南以当前仓库skills/cloud/spanner-basics技能包为蓝本系统梳理 Cloud Spanner 的实例/库管理、高性能 Schema 设计、命令行运维、多语言客户端开发、IAM 安全治理、Terraform 基础设施即代码、PostgreSQL 方言以及 MCP 智能体接入等完整知识体系。读完本文你将掌握从主键防热点设计到SPANNER_SYS性能诊断的一整套可落地实践并能直接将这些模式应用到 Agent 驱动的数据库研发工作流中。该技能位于 skills/cloud/spanner-basics/SKILL.md元数据将其归类为Databases领域定位是协助用户完成实例与数据库的供给、高性能 Schema 设计以及在 Spanner 中查询数据典型触发场景包括设计主键、编写 SQL 或客户端库代码、诊断性能问题。技能主体的 SKILL.md 与其 8 篇 references 文档构成了总纲 专项的知识结构下面逐层展开。Cloud Spanner 核心能力定位Cloud Spanner 是一个全托管的、面向关键任务的数据库服务它将关系型数据库的结构化优势与非关系型的水平扩展能力结合在一起见 references/core-concepts.md。在技能语境下Spanner 的关键特性可以归纳为四点全球规模Global Scale支持跨行、跨区域乃至跨大洲的水平扩展数据可在行、区域之间自由伸缩。强一致性Strong Consistency事务提供外部一致性external consistency所有读操作都能看到最近的写入这在多区域部署场景中极为关键。多方言Multi-Dialect同时支持 GoogleSQLANSI 2011 及扩展与 PostgreSQL 两种 SQL 方言。多模型Multi-Model整合关系型、键值、图Spanner Graph以及搜索能力一个数据库服务多种数据形态。从架构设计上看Spanner 面向从小规模应用到全球关键任务、高事务负载的广泛工作负载在强一致前提下可支撑最高 99.999% 的可用性目标。技能文档同时提示价格信息应以官方 Spanner Pricing 页面为准本仓库不涉及具体计费数据。核心原则性能优先与 Schema 设计取向SKILL.md 开篇即确立了这条技能的工作准则是整个技能包的方法论基石性能优先Performance FirstSpanner 是水平扩展的其效率与主键Primary Key设计强相关。技能明确要求永远要警告用户避免将单调递增/递减的值如顺序时间戳作为主键的首字段以防止热点hotspot。Schema 设计对于频繁一起访问、强关联的父子数据优先采用交错表interleaved tables。这两条原则会在后续的 Schema 设计章节和 DDL 工作流中被反复引用也是 Agent 审查代码时的高频检查点。安全准则非模拟器变更必须获得用户确认技能在 SKILL.md 中有一条醒目的安全红线 [!CAUTION]警示块在执行任何非模拟器的数据库变更DML 或 DDL或破坏性操作如删除表、索引或其他 Spanner 资源之前必须获得用户的明确确认。不得自动执行而是应输出命令例如gcloud spanner databases ddl update并等待用户显式批准。配套规则是当数据库访问不可用或认证失败时不要阻塞在验证实例、数据库或表是否存在的环节上而是假设所给资源存在并直接生成 DDL 命令。这一设计对 Agent 工作流非常关键——它既保证了生产环境的安全性防止 AI 擅自修改真实数据又保持了低延迟的执行体验认证失败不阻断生成流程。常用工作流Schema 演化与性能诊断SKILL.md 给出了两条高频工作流的操作主线工作流一Schema 演化与 DDL使用gcloud spanner databases ddl update应用 Schema 变更包括 CREATE、ALTER、DROP 表与索引。参考 references/schema-design.md 获取主键选择与交错表的设计准则。工作流二诊断性能问题使用SPANNER_SYS系统表识别慢查询或高资源消耗查询。例如查询SPANNER_SYS.QUERY_STATS_TOP_HOUR找出 CPU 占用最高的查询。这两个工作流分别指向了后续的 DDL 实战与 Schema 设计深度章节是连接技能指令与参考文档的枢纽。Schema 设计深度主键、热点防治与交错表references/schema-design.md 是技能包中性能含量最高的文档。Spanner 中热点产生的根源是主键首字段单调递增/递减如时间戳会把所有插入流量导向单一服务器形成瓶颈。文档给出了四种热点防治技术热点防治四种方案使用 UUID通用唯一标识符推荐UUID Version 4基于随机值。由于相关记录之间不保持局部性可彻底消除热点以UUID列存储。位反转顺序值Bit-reversed Sequential Values避免顺序递增/递减的数字主键将顺序值位反转后可使主键值均匀分布在整个键空间中Spanner 原生支持位反转序列bit-reversed sequences。交换键的顺序把高基数、非单调的列放在主键首位使写入更均匀地铺开。例如先按UserId排序再按时间戳LastAccess排序。哈希唯一键创建一列保存真实唯一键的哈希值用该哈希列作为主键从而将写入分散到各逻辑分片。时间戳键的降序设计如果满足以下条件应考虑对时间戳键使用降序DESC希望读取最近的历史记录且正在读取交错表interleaved table中的父行按逆时间顺序读取连续条目例如最近的 N 个事件。这与大多数默认升序索引的思维相反是 Spanner 中面向最新优先场景的常见优化手段。何时使用交错索引避免在值单调递增或递减的列如非主键时间戳上创建非交错索引在上次访问行与对应用户行这种父子关系下应使用交错索引interleaved index将子行交错存储在父行之下。数据类型与主键约束GoogleSQL 类型PostgreSQL 对应类型ARRAYarrayBOOLboolBYTESbyteaDATEdateENUM—FLOAT32float4FLOAT64float8INT64int8/bigintJSONjsonbNUMERICnumericPROTO—STRINGvarchar/textSTRUCT—TIMESTAMPtimestamptzUUIDuuid关键约束除FLOAT32、ARRAY、JSON、PROTO和STRUCT之外其余类型均可作为主键。Agent 性能检查清单可直接复用当审查或生成 Schema 相关代码时技能建议逐项核对热点防治确认主键首字段不是单调递增/递减的值如顺序 ID 或时间戳如果是建议改用 UUID(v4)、位反转序列或哈希。交错表确认频繁一起访问的强关联父子数据是否使用交错表结构INTERLEAVE IN PARENT。交错深度限制交错层级。Spanner 最多支持 7 层交错但应尽量保持最小深度以避免过高开销。索引设计为高频查询模式创建二级索引若需按时间戳排序检查索引是否应使用降序DESC。数据类型检查所选类型对该列用途是否最优且合法例如FLOAT32、ARRAY、JSON、STRUCT不能作主键。CLI 实战用 gcloud 管理实例与数据库references/cli-usage.md 汇总了常用的gcloud spanner命令覆盖实例、数据库、查询、备份与操作五个维度。实例管理# 列出实例 gcloud spanner instances list # 创建实例固定节点 gcloud spanner instances create my-instance \ --configregional-us-central1 \ --descriptionMy Instance \ --nodes1 # 创建实例自动扩缩容 gcloud spanner instances create my-autoscaled-instance \ --configregional-us-central1 \ --descriptionMy Autoscaled Instance \ --autoscaling-min-nodes1 \ --autoscaling-max-nodes3--nodes用于固定节点数计费模式而--autoscaling-min-nodes/--autoscaling-max-nodes则启用自动扩缩容让实例根据负载在 1~3 个节点区间内弹性伸缩适合负载波动明显的场景。数据库与查询# 列出数据库 gcloud spanner databases list --instancemy-instance # 创建数据库 gcloud spanner databases create my-database --instancemy-instance # 执行 SQL 查询 gcloud spanner databases execute-sql my-database --instancemy-instance --sqlSELECT 1备份与长时操作# 创建备份保留期 7 天 gcloud spanner backups create my-backup \ --instancemy-instance \ --databasemy-database \ --retention-period7d # 列出实例上的长时操作 gcloud spanner operations list --instancemy-instance这些命令与 SKILL.md 中Schema 演化与 DDL工作流的gcloud spanner databases ddl update一起构成了纯 CLI 场景下的完整运维闭环建实例 → 建库 → 改 Schema → 查询 → 备份 → 跟踪异步操作。多语言客户端库开发references/client-library-usage.md 提供了 Google Cloud 官方客户端库的安装与最小可运行示例覆盖 Python、Java、Node.js、Go 四种主流语言。Pythonpip install google-cloud-spannerfrom google.cloud import spanner spanner_client spanner.Client() instance spanner_client.instance(my-instance-id) database instance.database(my-database-id) with database.snapshot() as snapshot: results snapshot.execute_sql(SELECT 1) for row in results: print(row)Python 示例中的database.snapshot()对应只读快照事务是执行查询的推荐方式如需写入可改用database.batch()或读写事务。JavaMavendependency groupIdcom.google.cloud/groupId artifactIdgoogle-cloud-spanner/artifactId /dependencySpannerOptions options SpannerOptions.newBuilder().build(); Spanner spanner options.getService(); DatabaseClient dbClient spanner.getDatabaseClient(DatabaseId.of(options.getProjectId(), my-instance-id, my-database-id)); ResultSet resultSet dbClient.singleUse().executeQuery(Statement.of(SELECT 1)); while (resultSet.next()) { System.out.println(resultSet.getLong(0)); }Node.jsnpm install google-cloud/spannerconst {Spanner} require(google-cloud/spanner); const spanner new Spanner({projectId: my-project-id}); const instance spanner.instance(my-instance-id); const database instance.database(my-database-id); const [rows] await database.run({sql: SELECT 1});Gogo get cloud.google.com/go/spannerctx : context.Background() client, err : spanner.NewClient(ctx, projects/my-project-id/instances/my-instance-id/databases/my-database-id) if err ! nil { log.Fatalf(Failed to create client: %v, err) } defer client.Close() iter : client.Single().Query(ctx, spanner.Statement{SQL: SELECT 1}) defer iter.Stop()面向 LLM 应用的附加集成技能文档还特别列出了面向 LLM/Agent 应用的扩展能力LangChain 集成SpannerVectorStore用于向量嵌入的存储与检索SpannerLoader用于从 Spanner 加载数据SpannerChatMessageHistory用于存储对话历史——这与当前仓库Agent Skills for Google products and technologies的定位高度契合Spanner 可以作为 RAG 与 Agent 记忆层的后端存储。Spring Data Spanner为 Spring Framework 的 Java 应用提供熟悉的 Spring Data 接口可显著降低 Java 生态集成成本。IAM 安全与数据治理references/iam-security.md 给出了 Spanner 的预定义 IAM 角色清单与安全最佳实践。预定义角色对照表角色权限范围roles/spanner.admin对所有 Spanner 资源的完全控制roles/spanner.databaseAdmin对数据库、备份和操作的完全控制roles/spanner.databaseReader可读取数据并执行查询roles/spanner.databaseUser可读写数据roles/spanner.viewer可查看 Spanner 资源但无法访问数据安全最佳实践最小权限原则Principle of Least Privilege只授予用户和服务账号完成任务所需的最小权限。使用服务账号应用应使用服务账号service accounts而非个人用户账号。VPC Service Controls借助 VPC Service Controls 降低数据外泄风险。CMEK若安全策略要求使用客户管理的加密密钥Customer-Managed Encryption Keys。文档特别给出警示授予roles/spanner.admin将获得项目中所有 Spanner 资源的完全访问权必须谨慎使用——这与 SKILL.md 的安全红线相呼应构成了技能行为准则 IAM 权限边界的双重防护。基础设施即代码Terraform 供给references/terraform-usage.md 展示了如何使用 Terraform 对 Spanner 基础设施进行构建、变更与版本管理。Google Cloud Terraform Provider 支持以下 Spanner 资源google_spanner_instancegoogle_spanner_databasegoogle_spanner_instance_iamgoogle_spanner_database_iam完整的可运行配置示例resource google_spanner_instance example { name example-instance config regional-us-central1 display_name Example Instance nodes 1 } resource google_spanner_database example { instance google_spanner_instance.example.name name example-database }该配置与 CLI 章节的gcloud spanner instances create是对同一供给流程的两种表达方式CLI 适合交互式运维与快速原型Terraform 适合声明式、可版本化、可审计的持续交付场景。将nodes 1与 CLI 的--nodes1对比可见两者参数语义一致便于在两种工具间切换。PostgreSQL 方言支持references/postgresql-dialect.md 说明 Spanner 通过开放源码 PostgreSQL 方言构造的子集来表达 Spanner 数据库特性适合已有 PostgreSQL 经验的团队。关键考量可移植性Portability如需迁移到其他 PostgreSQL 数据库切换成本更低。熟悉度Familiarity直接复用既有的 PostgreSQL 语法与工具知识。生态Ecosystem支持psql以及 PostgreSQL 驱动通过 PGAdapter 桥接。方言内的 Spanner 扩展Spanner 在 PostgreSQL 方言中保留了 Spanner 特有能力的扩展包括交错表Interleaved tables、生命周期 TTLTime to live、查询提示Query hints。限制清单以下开源 PostgreSQL 特性在 Spanner 中不被支持触发器TriggersSERIAL事务性 DDLTransactional DDL用户自定义数据类型与运算符User-defined data types and operators选择方言时应结合团队技能栈与对上述限制的容忍度综合评估。该文档与 references/core-concepts.md 中的多方言Multi-Dialect特性互为印证。智能体接入Spanner MCP 服务器references/mcp-usage.md 说明 Spanner 通过模型上下文协议Model Context Protocol, MCP将数据库连接到 LLM Agent使 IDE 或应用能够使用 Spanner 预构建的 MCP 工具与数据库交互——这正是在本仓库的 Agent 生态plugins/cloud/data-agent-kit等模块中使用 Spanner 的关键路径。Spanner MCP 服务器向 LLM Agent 暴露的工具清单如下get_instance获取指定 Spanner 实例的信息list_instances列出项目中的所有 Spanner 实例list_configs列出项目中可用的实例配置get_config获取指定实例配置的信息create_instance创建新的 Spanner 实例update_instance更新 Spanner 实例create_database在给定实例中创建数据库get_database_ddl检索数据库 SchemaDDLlist_databases列出给定实例中的所有数据库create_session在数据库中创建会话以执行查询execute_sql执行 SQL 语句同时支持 DQL 与 DMLexecute_sql_readonly在单次只读事务中执行 SQL 查询语句commit提交事务update_database_schema更新指定数据库的 Schemaget_operation获取长时操作的状态可以观察到MCP 工具集与 CLI 命令、Terraform 资源形成了完整的三层操作映射create_instance/create_database对应gcloud spanner instances/databases createget_database_ddl/update_database_schema对应 DDL 管理execute_sql/commit对应查询与事务。这使 Agent 能够以自然语言驱动完整的数据库生命周期管理同时仍受 SKILL.md 中非模拟器变更需用户确认的安全约束。参考目录与进一步探索本技能包采用SKILL.md 总纲 references 专项的组织方式完整参考文件位于 skills/cloud/spanner-basics/references/按需查阅对应主题Core ConceptsSpanner 内部机制、架构与设计说明CLI Usage管理实例与数据库的gcloud spanner核心命令IAM Security角色、权限与数据治理最佳实践Client Library UsageJava、Go、Python、Node.js 客户端库使用Terraform Usage供给 Spanner 实例与数据库的 IaC 示例MCP UsageSpanner 远程 MCP 服务器的使用PostgreSQL DialectSpanner 中 PostgreSQL 接口的最佳实践与示例Schema Design主键选择与交错表的性能指南SKILL.md 同时提示如果上述参考文档未能覆盖所需的产品信息可以调用 Developer Knowledge MCP 服务器的search_documents工具检索官方产品文档。这保证了 Agent 在技能知识边界之外仍能获取权威信息也保持了技能包自身的轻量与聚焦。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考