skills29 中的 cloud-sql-basics 技能解析Cloud SQL 实例创建、安全连接与灾备恢复的完整实战指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本篇基于 skills29 仓库中cloud-sql-basics技能文档SKILL.md及其配套的 7 份参考文档系统讲解 Google Cloud 托管关系型数据库 Cloud SQL 的核心概念与操作体系读者将掌握从启用 API、创建 PostgreSQL 实例到通过 Auth Proxy 安全连接的全流程以及 Editions 选型、读池架构、备份与 PITR、Terraform 声明式配置、IAM 最小权限实践和 MCP 自动化管理等进阶能力。1. 技能定位与前置条件cloud-sql-basics是 skills29 仓库中面向 Google Cloud 数据库方向的一个 Agent 技能其元数据明确定义了触发场景当用户要求创建或解释 Cloud SQL 的 MySQL、PostgreSQL 或 SQL Server 实例/数据库时使用该技能。技能说明中指出Cloud SQL 将第三方的 MySQL、PostgreSQL、SQL Server 实例作为托管资源管理——例如创建一个开源 MySQL 实例得到的实际是一个由 Google Cloud 托管的 Cloud SQL for MySQL 实例其备份、高可用和安全连接均由平台负责。在开始操作前技能文档要求确认两个前置条件已安装并认证 Google Cloud SDK当前身份具备创建和管理 Cloud SQL 实例的 IAM 权限。其中Cloud SQL Adminroles/cloudsql.admin角色提供对 Cloud SQL 资源的完全访问权限适合部署流水线或专职 DBA 使用安全边界详见第 7 节。2. 快速上手六步创建一个可连接的 PostgreSQL 实例SKILL.md 的核心是一条完整的 PostgreSQL 快速上手路径覆盖从 API 启用到客户端连接的全部步骤。以下命令均可直接复制执行将占位符替换为实际值2.1 启用 Cloud SQL Admin APIgcloud services enable sqladmin.googleapis.com --quiet2.2 创建实例gcloud sql instances create INSTANCE_NAME \ --database-versionPOSTGRES_18 \ --cpu2 \ --memory7680MiB \ --regionREGION \ --quiet示例中使用了POSTGRES_18作为数据库版本——根据核心概念文档PostgreSQL 18 是当前 Cloud SQL 的默认引擎版本可选版本还覆盖 9.617。--cpu与--memory指定自定义机型规格示例为 2 vCPU / 7680 MiB 内存。2.3 为默认管理员用户设置密码PostgreSQL 实例的默认管理员用户是postgresgcloud sql users set-password postgres \ --instanceINSTANCE_NAME --passwordPASSWORD \ --quiet2.4 创建数据库gcloud sql databases create DATABASE_NAME \ --instanceINSTANCE_NAME \ --quiet2.5 获取实例连接名Cloud SQL Auth Proxy 需要格式为PROJECT_ID:REGION:INSTANCE_NAME的实例连接名gcloud sql instances describe INSTANCE_NAME \ --formatvalue(connectionName) \ --quiet2.6 启动 Auth Proxy 并连接在单独终端中启动 Cloud SQL Auth Proxy./cloud-sql-proxy INSTANCE_CONNECTION_NAME代理运行后在另一个终端使用psql通过本地回环地址连接psql host127.0.0.1 port5432 userpostgres dbnameDATABASE_NAME passwordPASSWORD sslmodedisable这条命令体现了 Auth Proxy 的工作方式代理在本地监听 5432 端口并完成 IAM 认证与端到端加密客户端只需连接127.0.0.1因此无需配置 IP 白名单或 SSL 证书。3. Editions 选型Enterprise 与 Enterprise Plus参考文档 core-concepts.md 给出了两个版本的关键差异这是架构选型的核心依据维度EnterpriseEnterprise Plus适用负载需要标准托管数据库能力的核心业务应用需要最高可用性、最大读性能、最小运维中断的关键业务可用性 SLA99.95%不含计划内维护99.99%含计划内维护硬件共享核心 VM至多 1 vCPU / 1.7 GB RAM或专用核心 VM至多 96 vCPU / 624 GB RAMN4 机型至多 80 vCPU / 624 GB RAMN2、C4A 高性能机型至多 128 vCPU / 864 GB RAM配 SSD 数据缓存读性能最高可提升 4 倍维护停机标准维护影响 30 秒维护与计划内扩容操作均 1 秒PITR 日志保留至多 7 天35 天独占能力—Read Pools、托管连接池、跨区域写端点的 Advanced DREnterprise Plus 还支持从 Enterprise就地升级停机时间最小或亚秒级。支持的引擎版本包括MySQL5.6、5.7、8.0、8.4PostgreSQL9.6、1017、18默认SQL Server2017Express/Web/Standard/Enterprise、2019、2022、2025Express/Enterprise/Standard。4. 实例架构主实例、HA、读副本与读池每个 Cloud SQL 实例由一台运行数据库程序的虚拟机VM驱动参考文档 core-concepts.md 定义了四种拓扑角色主实例Primary Instance主要读写连接点高可用HA在同区域的不同可用区放置一个备用 VM自动故障切换读副本Read Replicas独立单节点实例用于扩展读流量和跨区域本地读访问读池Read Pools面向高并发读负载的多节点负载均衡读节点组。读池是 Enterprise Plus 版本新网络架构的独占能力文档给出了详细约束节点数量MySQL 与 PostgreSQL 为 120 个读池节点SQL Server 为 17 个每个主实例下独立读副本与读池节点总数不可超过 20MySQL/PostgreSQL或 7SQL Server扩缩容手动扩缩增删节点、变更机型档位为亚秒级停机自动扩缩基于AVERAGE_CPU_UTILIZATION或AVERAGE_DB_CONNECTIONS在--auto-scale-min-node-count与--auto-scale-max-node-count阈值间动态调整支持可配置冷却期默认 600 秒、最小 60 秒以及通过--auto-scale-disable-scale-in禁用缩容SLA 与路由2 个及以上节点的池受 Cloud SQL SLA 覆盖节点分布在区域内不同可用区流量按节点进程健康状况路由与复制延迟无关跨节点的不同请求之间不保证 read-your-own-writes 一致性各节点 LSN/GTID 进度可能不同拓扑限制读池必须直接从主实例复制不支持级联读池或从级联读副本复制到读池。存储与网络方面持久盘Persistent Disk提供可扩展的持久网络存储连接方式支持私网 IPMySQL/PostgreSQL 可用 VPC peering全部引擎可用 Private Services Access 或 Private Service Connect和公网 IP配合授权网络或 Auth Proxy。计费维度包括实例规格vCPU/RAM、存储与 IOPS、网络出口与 IP 使用、DNS 按区域计费以及仅 SQL Server 的许可证费用HA/区域实例只按一个活跃资源计费不支持 BYOL。5. gcloud CLI 完整操作手册参考文档 cli-usage.md 给出了gcloud sql命令组的生产级用法基础语法为gcloud sql [GROUP] [COMMAND] [FLAGS]。5.1 实例管理创建主实例注意与快速上手示例的差异这里显式声明了 Edition、机型档位、SSL 模式和 PITRgcloud sql instances create my-instance \ --database-versionPOSTGRES_18 \ --editionENTERPRISE \ --tierdb-custom-2-7680 \ --regionus-central1 \ --ssl-modeENCRYPTED_ONLY \ --enable-point-in-time-recovery \ --database-flagscloudsql.iam_authenticationon \ --quiet创建 Enterprise Plus 读池多节点负载均衡绑定到主实例gcloud sql instances create my-read-pool \ --master-instance-namemy-instance \ --instance-typeREAD_POOL_INSTANCE \ --editionENTERPRISE_PLUS \ --tierdb-perf-optimized-N-2 \ --node-count2 \ --no-assign-ip \ --quiet创建单节点读副本、列表、描述与重启gcloud sql instances create my-replica \ --master-instance-namemy-instance \ --quiet gcloud sql instances list --quiet gcloud sql instances describe my-instance --quiet gcloud sql instances restart my-instance --quiet5.2 数据库与用户管理# 创建数据库 gcloud sql databases create my-db --instancemy-instance --quiet # 创建 IAM 数据库用户推荐用 IAM 身份替代静态密码 gcloud sql users create user-emailexample.com \ --instancemy-instance \ --typeCLOUD_IAM_USER \ --quiet # 创建静态密码用户 gcloud sql users create my-user --instancemy-instance \ --passwordmy-password \ --quiet文档将 IAM 数据库用户标记为推荐方式这与第 7 节中 IAM 认证IAM Database Authentication的讨论相互印证——应用运行时凭据不再落库。5.3 运维与备份操作# 查看实例运维操作 gcloud sql operations list --instancemy-instance --quiet # 创建备份 gcloud sql backups create --instancemy-instance --quiet # 恢复到产生备份的同一实例 gcloud sql backups restore backup_id --restore-instancemy-instance --quiet # 恢复到另一目标实例必须用 --backup-instance 指明备份来源实例 gcloud sql backups restore backup_id \ --restore-instancetarget-instance \ --backup-instancesource-instance \ --quiet5.4 常用参数速查参数说明--project指定 Google Cloud 项目 ID--region实例所在区域--edition数据库版本档位ENTERPRISE或ENTERPRISE_PLUS--tier机型档位如db-custom-2-7680、db-perf-optimized-N-2--ssl-modeSSL 强制模式ALLOW_UNENCRYPTED_AND_ENCRYPTED、ENCRYPTED_ONLY、TRUSTED_CLIENT_CERTIFICATE_REQUIRED--database-flags数据库参数如cloudsql.iam_authenticationon--tags附加 Resource Manager 标签如tagKeys/123456789012tagValues/987654321098--format输出格式如json、yaml6. 客户端库连接与 Terraform 声明式配置6.1 语言连接器参考文档 client-library-usage.md 介绍的四类语言连接器Python、Java、Go、Node.js提供安全连接通道无需管理 IP 白名单或 SSL 证书。PythonCloud SQL for PostgreSQLpip install cloud-sql-python-connector[pg8000]from google.cloud.sql.connector import Connector connector Connector() def getconn(): conn connector.connect( project:region:instance, pg8000, usermy-user, passwordmy-password, dbmy-db ) return connJava推荐 JDBC Socket Factory先引入 BOM 再按引擎添加依赖dependencyManagement dependencies dependency groupIdcom.google.cloud.sql/groupId artifactIdjdbc-socket-factory-bom/artifactId version1.18.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagementPostgreSQL 引擎依赖dependencies dependency groupIdorg.postgresql/groupId artifactIdpostgresql/artifactId version42.7.3/version /dependency dependency groupIdcom.google.cloud.sql/groupId artifactIdpostgres-socket-factory/artifactId /dependency /dependenciesMySQL 引擎则使用mysql-connector-j8.0.33搭配mysql-socket-factory-connector-j-8构件。Node.js (TypeScript)npm install google-cloud/cloud-sql-connectorGogo get cloud.google.com/go/cloudsqlconn此外文档还指出管理面操作如程序化列出实例应使用sqladmin客户端库即 Cloud SQL Admin API。6.2 Terraform 配置参考文档 iac-usage.md 给出完整的实例 数据库 IAM 用户三件套resource google_sql_database_instance default { name master-instance region us-central1 database_version POSTGRES_18 deletion_protection false # 生产环境建议设为 true 防止误删 settings { tier db-custom-1-3840 edition ENTERPRIRE settings { tier db-custom-1-3840 edition ENTERPRISE # 启用 IAM 数据库认证所必需的 database flag database_flags { name cloudsql.iam_authentication value on } backup_configuration { enabled true point_in_time_recovery_enabled true } } } }以上代码块请以 iac-usage.md 原文为准核心结构为settings块内声明tier、edition、database_flags与backup_configuration。配套的数据库与 IAM 用户资源resource google_sql_database database { name my-database instance google_sql_database_instance.default.name } # IAM Database Authentication依赖 cloudsql.iam_authentication on resource google_sql_user iam_user { name user-emailexample.com instance google_sql_database_instance.default.name type CLOUD_IAM_USER }文档强调四个关键配置要点IAM 认证 flagPostgreSQL 使用cloudsql.iam_authentication onMySQL 使用下划线命名的cloudsql_iam_authentication on且用户或服务账号还需授予roles/cloudsql.instanceUser删除保护provider 默认deletion_protection true开发/测试环境如需执行terraform destroy须显式置falsePITRbackup_configuration中enabled true开启每日自动备份需额外显式设置point_in_time_recovery_enabled true才启用连续 WAL 归档Edition 声明在settings内显式声明edition以固定功能集与 SLA 等级。7. IAM 与数据安全参考文档 iam-security.md 是全文档中最厚重的部分覆盖预定义角色、最小权限、连接安全、审计与暴力破解防护。7.1 预定义 IAM 角色预定义角色用途roles/cloudsql.admin完全控制所有 Cloud SQL 资源roles/cloudsql.editor管理 Cloud SQL 资源但不可查看/修改权限、不可修改用户或 SSL 证书、不可导入数据或从备份恢复、不可克隆/删除/提升实例、不可启动/停止副本、不可删除数据库/副本/备份roles/cloudsql.viewer只读访问roles/cloudsql.client从 App Engine 和 Auth Proxy 连接实例的权限按 IP 直连不需要roles/cloudsql.instanceUser登录实例的权限roles/cloudsql.schemaViewer在 Knowledge Catalog 中访问实例 schemaroles/cloudsql.studioUser访问 Cloud SQL Studio最小权限实践的核心是职责分离roles/cloudsql.admin仅用于开通与创建实例的部署流水线或专职 DBA应用连接使用roles/cloudsql.clientroles/cloudsql.instanceUser避免在数据库访问上使用roles/editor/roles/owner等宽泛项目级角色。文档特别警告了setIamPolicy的提权风险包含cloudsql.instances.setIamPolicy的角色roles/cloudsql.admin、roles/resourcemanager.projectIamAdmin、roles/owner注意roles/cloudsql.editor不包含该权限允许持有者修改 IAM 策略并自我提权应限制给 CI/CD 流水线或安全管理员并开启 Data Access 审计日志与 IAM 角色推荐功能检测过度授权。为部署服务账号授予实例创建权限的示例gcloud projects add-iam-policy-binding project_id \ --memberserviceAccount:deployment_saproject_id.iam.gserviceaccount.com \ --roleroles/cloudsql.admin7.2 连接安全与 SSL 强制Cloud SQL Auth Proxy是推荐连接方式提供基于 IAM 的认证与端到端加密免 SSL 证书与授权网络配置私网 IP经 VPC、Private Services Access 或 PSC 保持流量在 Google Cloud 网络内部公网 IP 则必须限制授权网络 CIDRVPC-SC可围绕实例建立安全边界防止数据外泄。服务端证书 CA 层级serverCaMode三选一GOOGLE_MANAGED_INTERNAL_CA每实例独立 CA、GOOGLE_MANAGED_CAS_CA区域共享 CA、CUSTOMER_MANAGED_CAS_CA客户自管 CA。文档推荐客户自管 CA以保留信任锚点所有权、使用现代 ECDSA 256 位密钥并支持自定义 DNS 命名。SSL/TLS 强制实例sslMode/ CLI--ssl-mode/ Terraformssl_mode三档ALLOW_UNENCRYPTED_AND_ENCRYPTED默认明文与加密连接都允许ENCRYPTED_ONLY仅允许 SSL/TLS 加密流量TRUSTED_CLIENT_CERTIFICATE_REQUIRED强制 mTLS要求客户端证书。推荐后两者以避免明文传输凭据。注意实施差异MySQL 与 SQL Server 强制 SSL 会自动重启实例PostgreSQL 对新连接立即生效但既有明文连接在手动重启前仍保持活跃。7.3 数据安全与审计静态加密默认开启可用 CMEK 增强控制IAM 数据库认证MySQL/PostgreSQL 可用用 IAM 身份替代静态密码密码策略实例级password_validation_policy强制最小长度、复杂度COMPLEXITY_DEFAULT、复用限制并禁止用户名子串MySQL 8.0 支持用户级策略——密码过期、失败锁定--password-policy-allowed-failed-attempts、当前密码校验通过gcloud sql users set-password-policy配置客户端加密对列级敏感数据卡号、PII使用 Tink 加密库 Cloud KMS 密钥实现数据库查询权限 KMS 解密权限的双重访问控制审计日志Admin Activity 默认开启Data Access 需在 IAM 配置中显式启用。引擎级审计各有开关——MySQL 开cloudsql_mysql_auditflag需重启PostgreSQL 开cloudsql.enable_pgauditon需重启后执行CREATE EXTENSION pgaudit;并配置pgaudit.log如all或writeSQL Server 用--audit-bucket-path指定 Cloud Storage 桶上传审计日志需重启暴力破解防护平台自动跟踪失败连接并引入实时响应延迟throttling配合 MySQL 8.0 账户锁定与 Security Command Center 事件威胁检测文档推荐的根本缓解手段仍是 IAM 认证或 Auth Proxy彻底消除静态凭据这一攻击面。此外文档还覆盖组织策略约束组织内实例配置方式、Resource Manager 标签与 IAM 条件集成区别于仅用于计费的 labelsgcloud 中推荐用tagKeys/IDtagValues/ID资源 ID 形式或ORG_ID/KEY/VALUE命名空间路径经--tags参数在创建时附加以及实例服务账号命名规则p[PROJECT_NUMBER]-[UNIQUE_ID]gcp-sa-cloud-sql.iam.gserviceaccount.com用于导出 SQL dump 到 Cloud Storage 等任务。8. 备份、PITR 与高级灾备参考文档 dr-backups.md 构建了完整的灾备矩阵。8.1 备份类型自动备份每日快照在可配置的 4 小时窗口内执行Enterprise 默认保留至多 7 份Enterprise Plus 支持保留至 35 天按需备份手动创建、直到显式删除一直保留适合高风险 schema 迁移或运维变更前打点增强备份Enhanced Backups与 Backup and DR Service 集成提供集中治理与合规能力——备份存放到逻辑隔离的独立气隙不可变项目防勒索与误删、保留期最长 10 年标准备份为 1 年、支持小时/日/周/月/年计划、保留锁保留期内不可删除修改、跨项目恢复工作流PITR基于连续事务日志MySQL 二进制日志、PostgreSQL WAL、SQL Server 事务日志恢复到任意秒保留上限 7 天Enterprise/ 35 天Enterprise Plus最终备份删除实例或故障切换重建前自动拍摄的状态快照备份位置默认存放在离实例最近的多区域位置也可指定区域/多区域桶可恢复到原实例或新目标实例。标准备份与增强备份的对比特性标准备份增强备份管理方式实例级 Cloud SQL 备份集中式 Backup and DR Service存储库同项目/多区域桶独立气隙不可变备份项目最长保留1 年10 年调度每日4 小时可配窗口小时/日/周/月/年保留锁不支持支持强制保留策略跨项目恢复标准恢复至项目内目标集中式跨项目恢复工作流计费Cloud SQL 备份存储计费Backup and DR Service 计费模型8.2 复制与高可用HA 备用副本同区域次可用区的备用 VM同步复制 主节点硬件/可用区故障时即时故障切换独立读副本异步只读实例可用区级或跨区域用于扩展查询流量与本地读MySQL/PostgreSQL 至多 20 个、SQL Server 至多 7 个级联副本从另一个读副本而非主实例复制降低主实例复制压力。高级灾备Advanced DR为 Enterprise Plus 独占指定跨区域 DR 读副本作为恢复目标副本故障切换主区域宕机时快速跨区域切换将 DR 副本提升为主并保留旧主在复制拓扑中以便后续恢复与切换Switchover零数据丢失、零停机的计划内跨区域切换或 DR 演练配套DNS 写端点——全局 DNS 地址在切换后自动将写流量导向新提升的主实例。8.3 读池 vs 读副本架构对比特性独立读副本读池节点主要用途读扩展与跨区域 DR 切换目标高并发、负载均衡的区域读流量拓扑直接从主实例或级联复制仅直接复制无级联连接端点独立 IP/连接名单一负载均衡 IP/连接名池DR 与提升可提升为独立主实例不可直接提升为主扩展机制逐实例创建/删除手动或自动扩缩120 节点8.4 灾备 CLI 操作速查# 开启自动备份与 PITR gcloud sql instances patch my-instance \ --backup-start-time03:00 \ --enable-point-in-time-recovery \ --quiet # 创建带描述的按需备份 gcloud sql backups create --instancemy-instance \ --descriptionPre-migration snapshot \ --quiet # 列出备份 gcloud sql backups list --instancemy-instance --quiet # PITR 克隆到指定 RFC 3339 时间戳 gcloud sql instances clone source-instance restored-instance \ --point-in-time2026-07-16T12:00:00Z \ --quiet # 模拟/触发 HA 故障切换测试用 gcloud sql instances failover my-ha-instance --quiet # Enterprise Plus 计划内 DR 切换零数据丢失 gcloud sql instances switchover my-dr-replica --quiet # 将读副本提升为独立主实例 gcloud sql instances promote-replica my-replica --quiet9. MCP 集成让 Agent 管理 Cloud SQL参考文档 mcp-usage.md 展示了该技能与 Agent 工作流的结合面。Cloud SQL 远程 MCP 服务器暴露 15 个工具覆盖管理、查询与备份全流程实例生命周期create_instance、clone_instance、get_instance、update_instance、list_instances、get_operation数据面execute_sql执行任意 DDL/DCL/DQL/DML、execute_sql_readonly安全只读查询用户管理create_user、update_user、list_users备份与迁移create_backup、restore_backup、import_data从 Cloud Storage 导入版本升级postgres_upgrade_precheckPostgreSQL 引擎升级前检查。端点与权限模型全量工具集端点https://sqladmin.googleapis.com/mcp暴露全部管理、查询、备份工具只读工具集端点https://sqladmin.googleapis.com/mcp/readonly限制为execute_sql_readonly等只读工具使用远程 MCP 服务器需要roles/mcp.toolUser角色外加Cloud SQL 资源角色如roles/cloudsql.admin或roles/cloudsql.editor——这一双层权限设计呼应了第 7 节的最小权限原则。在此之上Agent 可自动化的场景包括数据库 schema 迁移、按需创建/恢复备份、PostgreSQL 引擎版本升级预检、健康检查与运维日志监控、只读或全量 SQL 执行辅助的性能问题调试。另外文档还提到可本地安装的 MCP Toolbox for databases为 Cloud SQLPostgreSQL/MySQL/SQL Server提供预定义与自定义工具。10. 参考文档导航与知识扩展机制SKILL.md 末尾以Reference Directory组织了指向 7 份参考文档的索引本文各节与其一一对应参考文档覆盖主题core-concepts.mdEditions、实例架构、读池、HA、支持引擎cli-usage.md实例/数据库/用户管理的核心 gcloud 命令client-library-usage.mdPython、Java、Node.js、Go 连接mcp-usage.mdCloud SQL 远程 MCP 服务器与 MCP Toolboxiac-usage.mdTerraform 实例/数据库/用户配置iam-security.md预定义角色、SSL/TLS 证书、Auth Proxy 配置dr-backups.md备份类型、PITR、副本、读池对比、Advanced DR值得注意的设计细节SKILL.md 结尾还内置了一条知识扩展规则——若在上述参考文档中找不到所需产品信息使用 Developer Knowledge MCP 服务器的search_documents工具。这与仓库中 retrieving-developer-knowledge 技能形成呼应构成本地参考文档优先、远程文档检索兜底的两级知识获取策略保证 Agent 在遇到文档未覆盖的产品细节时不会凭空作答。11. 小结cloud-sql-basics技能以 SKILL.md 的六步 PostgreSQL 快速上手为主干配合 7 份参考文档展开为完整的能力版图Editions 选型第 3 节、四种拓扑角色与读池约束第 4 节、覆盖实例/用户/备份全生命周期的 gcloud 命令与参数速查第 5 节、四语言连接器与 Terraform 三件套第 6 节、以最小权限与setIamPolicy提权风险为核心的安全体系第 7 节、标准/增强备份 PITR Advanced DR 的灾备矩阵第 8 节以及 MCP 双端点的 Agent 自动化面第 9 节。所有命令、参数取值与架构约束均可在 skills/cloud/cloud-sql-basics/ 目录下的源文档中逐项核验适合作为在 Google Cloud 上落地 Cloud SQL 时查阅与引用的完整操作基线。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考