尧图网站建设 
MCP Toolbox for Databases 实战:cloud-sql-postgres-create-instance 工具通过预设一键创建 Cloud SQL PostgreSQL 实例【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本篇技术指南以 MCP Toolbox for Databases 仓库中cloud-sql-postgres-create-instance工具的官方文档为主体,完整覆盖其配置字段、输入参数与预设(Production/Development)机制,并结合仓库源码深入剖析预设到sqladmin.Settings的映射、参数默认值注入、底层 Cloud SQL Admin API 调用链以及集成测试的验证方式,读完后你将能够独立配置该工具、理解其运行时行为,并正确编排实例创建与后续操作的完整工作流。工具概述cloud-sql-postgres-create-instance工具基于Cloud SQL Admin API创建 Cloud SQL for PostgreSQL 实例。与直接编写 gcloud 命令或手工调用 REST API 不同,该工具把创建实例这一管理操作封装为一个 MCP 工具,使 AI Agent 可以按预设模板自动完成实例创建。工具的官方文档位于 cloudsqlpgcreateinstances.md,它属于 Cloud SQL Admin 集成的一部分。该集成下的所有工具都依赖同一个cloud-sql-adminsource 提供 API 客户端,source 的详细配置参考见 Cloud SQL Admin Source。前置条件:配置 cloud-sql-admin Source该工具通过source字段绑定一个cloud-sql-admin类型的 source。根据 Cloud SQL Admin Source 文档,source 支持以下配置字段:字段类型必填说明typestring是必须为cloud-sql-admindefaultProjectstring否用于 Cloud SQL 基础设施工具的 Google Cloud 项目 IDuseClientOAuthboolean否为true时使用客户端侧 OAuth 授权,否则使用 Application Default Credentials(ADC),默认falsereadOnlyboolean否为true时抑制具备写能力的管理工具,默认falsesource 的两种认证方式在源码 cloud_sql_admin.go 的Initialize方法中实现:默认走 ADC(google.FindDefaultCredentials);当useClientOAuth为true时,每次请求由客户端(如 Web 浏览器)提供 OAuth 2.0 access token,并在GetService中用该 token 构造独立的sqladmin.Service实例。需要特别注意:创建实例属于写操作,若 source 设置了readOnly: true,该工具应被抑制。一个最小可用的 source 配置如下(摘自文档示例):kind: source name: my-cloud-sql-admin type: cloud-sql-admin工具配置示例文档给出的标准 YAML 配置如下,description字段完整描述了两个预设的行为,对 Agent 的决策有直接引导作用:kind: tool name: create-sql-instance type: cloud-sql-postgres-create-instance source: cloud-sql-admin-source description: Creates a Postgres instance using Production and Development presets. For the Development template, it chooses a 2 vCPU, 16 GiB RAM, 100 GiB SSD configuration with Non-HA/zonal availability. For the Production template, it chooses an 8 vCPU, 64 GiB RAM, 250 GiB SSD configuration with HA/regional availability. The Enterprise Plus edition is used in both cases. The default database version is POSTGRES_17. The agent should ask the user if they want to use a different version.工具配置参数(Tool Configuration)文档定义的工具配置字段如下:字段类型必填说明typestring是必须为cloud-sql-postgres-create-instancesourcestring是要使用的cloud-sql-adminsource 名称descriptionstring否工具描述从源码结构看(cloudsqlpgcreateinstances.go 的Config结构体),除了文档列出的三个字段外,还支持可选的annotations字段用于自定义工具注解。另外有两点源码级细节值得注意:默认描述回退:Initialize方法中,当description为空时会自动填充一段默认描述,内容与上文 YAML 示例中的description完全一致——也就是说文档示例中的描述其实就是源码内置的默认值,用户可省略该字段。破坏性注解:工具通过tools.NewDestructiveAnnotations标记为破坏性(destructive)工具,提示 Agent/用户该操作会产生真实的云资源。工具输入参数(Tool Inputs)文档定义的输入参数及源码中的默认值如下:参数类型必填默认值说明projectstring是若 source 配置了defaultProject则预填GCP 项目 IDnamestring是—实例名称databaseVersionstring否POSTGRES_17PostgreSQL 数据库版本,未指定时默认使用最新可用版本(如POSTGRES_17)rootPasswordstring是—实例 root 密码editionPresetstring否Development实例预设,取值为Production或Development,决定默认机型与可用性其中databaseVersion默认POSTGRES_17与editionPreset默认Development这两个默认值在源码buildParams函数中通过parameters.WithStringDefault注入,与文档描述一致。还有一个容易忽略但很实用的机制:当绑定的 source 配置了defaultProject时,project参数会被预填该值,且参数描述会变为 This is pre-configured; do not ask for it unless the user explicitly provides a different one(该值已预配置,除非用户显式提供不同值,否则不要向用户询问)。从源码结构看,这是通过resolveParams在工具解析阶段对比 source 的GetDefaultProject()动态生成的,目的是减少 Agent 在每次调用时的多余提问。预设机制:Production 与 Development 的映射关系editionPreset是本工具的核心设计——它把选机型、选可用性、选磁盘这一组决策收敛为单一参数。Invoke方法中的 switch 分支(大小写不敏感)定义了两种预设到sqladmin.Settings的精确映射:设置项ProductionDevelopmentAvailabilityTypeREGIONAL(HA,区域级)ZONAL(非 HA,可用区级)EditionENTERPRISE_PLUSENTERPRISE_PLUSTierdb-perf-optimized-N-8(8 vCPU)db-perf-optimized-N-2(2 vCPU)DataDiskSizeGb250GiB100GiBDataDiskTypePD_SSDPD_SSD这与工具描述中Production 为 8 vCPU / 64 GiB RAM / 250 GiB SSD / HA,Development 为 2 vCPU / 16 GiB RAM / 100 GiB SSD / 非 HA,两者均使用 Enterprise Plus 版的说明完全吻合(内存规格由db-perf-optimized-N-*机型隐式决定)。若传入其他取值,工具会返回 Agent 错误:invalid editionPreset: ... Must be either Production or Development。执行流程与底层 API 调用工具的调用链为:Invoke→ source 的CreateInstance→ Cloud SQL Admin API 的instances.insert。参数校验:Invoke从参数映射中逐一取出project、name、databaseVersion、rootPassword、editionPreset,任一缺失即返回util.NewAgentError。Agent 错误与常规服务错误语义不同,它指示 Agent 应补齐参数后重试,而不是把请求判为系统故障。构造实例对象:source 层的CreateInstance方法将参数组装为sqladmin.DatabaseInstance{Name, DatabaseVersion, RootPassword, Settings, Project},注意rootPassword仅在此创建阶段传入。发起请求:调用service.Instances.Insert(project, instance).Do(),即 Cloud SQL Admin API 的实例创建接口;请求发出后 Cloud SQL 返回一个Operation 资源(例如{name: op1, status: PENDING}),工具原样将该 operation 返回给调用方,真正的建实例过程是异步的。错误处理:API 错误经util.ProcessGcpError统一包装后返回。因此,完整的自动化建库工作流通常是:调用create_instance拿到 operation → 用同集成的cloud-sql-wait-for-operation工具轮询至完成 → 再用cloud-sql-create-database、cloud-sql-create-users等工具初始化库与账号。这些工具在仓库的预置配置 cloud-sql-postgres-admin.yaml 中已被组织进cloud_sql_postgres_admin_tools工具集:kind: source name: cloud-sql-admin-source type: cloud-sql-admin defaultProject: ${CLOUD_SQL_POSTGRES_PROJECT:} readOnly: ${CLOUD_SQL_POSTGRES_READONLY:false} --- kind: tool name: create_instance type: cloud-sql-postgres-create-instance source: cloud-sql-admin-source # ... 同文件还定义了 get_instance、list_instances、create_database、 # list_databases、create_user、wait_for_operation、clone_instance、 # postgres_upgrade_precheck、create_backup、restore_backup 等工具 --- kind: toolset name: cloud_sql_postgres_admin_tools tools: - create_instance # ... 以及上述其余工具可见预置配置通过defaultProject支持从环境变量CLOUD_SQL_POSTGRES_PROJECT注入默认项目、通过CLOUD_SQL_POSTGRES_READONLY控制只读模式,配合前文project 参数预填机制,部署后可实现零提问的项目绑定。集成测试验证仓库在 cloud_sql_pg_create_instances_test.go 中提供了端到端测试,用一个httptest假服务器把https://sqladmin.googleapis.com的请求劫持到本地,并逐字段断言请求体,验证了本文的关键论断:Production 用例:请求体断言AvailabilityType: REGIONAL、Edition: ENTERPRISE_PLUS、Tier: db-perf-optimized-N-8、DataDiskSizeGb: 250、DataDiskType: PD_SSD,与源码映射一致;Development 用例:断言ZONAL/db-perf-optimized-N-2/100GiB,且未传databaseVersion时请求体使用默认值POSTGRES_17(印证了默认值注入);缺参用例:仅传name时,API 返回{error:parameter \project\ is required};测试同时校验了请求User-Agent头必须携带genai-toolbox/标识。适用前提与注意事项该工具创建的是真实计费的 GCP 资源且被标记为破坏性工具,source 的readOnly开关、Agent 的确认机制是主要的防护手段;认证依赖 ADC 或客户端 OAuth,运行环境必须具备sqladmin相关 API 的访问凭据(见 source 文档);工具本身只负责发起创建并返回 operation,不等待实例就绪——轮询请配合cloud-sql-wait-for-operation工具完成;rootPassword为必填参数,创建完成后实例即以该密码提供postgres超级用户的访问;数据库版本默认POSTGRES_17,如需其他版本(如POSTGRES_15,测试用例即以此验证了显式传参路径)需显式传入databaseVersion。综合来看,这个工具的价值在于把 Cloud SQL 实例创建中最易出错的部分——机型选择、HA 可用性、磁盘规格的组合决策——固化为两个经过验证的预设,同时保留了databaseVersion等关键自由度,并通过预置defaultProject机制把 Agent 的交互成本降到最低。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MCP Toolbox for Databases 实战:cloud-sql-postgres-create-instance 工具通过预设一键创建 Cloud SQL PostgreSQL 实例
MCP Toolbox for Databases 实战:cloud-sql-postgres-create-instance 工具通过预设一键创建 Cloud SQL PostgreSQL 实例【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本篇技术指南以 MCP Toolbox for Databases 仓库中cloud-sql-postgres-create-instance工具的官方文档为主体,完整覆盖其配置字段、输入参数与预设(Production/Development)机制,并结合仓库源码深入剖析预设到sqladmin.Settings的映射、参数默认值注入、底层 Cloud SQL Admin API 调用链以及集成测试的验证方式,读完后你将能够独立配置该工具、理解其运行时行为,并正确编排实例创建与后续操作的完整工作流。工具概述cloud-sql-postgres-create-instance工具基于Cloud SQL Admin API创建 Cloud SQL for PostgreSQL 实例。与直接编写 gcloud 命令或手工调用 REST API 不同,该工具把创建实例这一管理操作封装为一个 MCP 工具,使 AI Agent 可以按预设模板自动完成实例创建。工具的官方文档位于 cloudsqlpgcreateinstances.md,它属于 Cloud SQL Admin 集成的一部分。该集成下的所有工具都依赖同一个cloud-sql-adminsource 提供 API 客户端,source 的详细配置参考见 Cloud SQL Admin Source。前置条件:配置 cloud-sql-admin Source该工具通过source字段绑定一个cloud-sql-admin类型的 source。根据 Cloud SQL Admin Source 文档,source 支持以下配置字段:字段类型必填说明typestring是必须为cloud-sql-admindefaultProjectstring否用于 Cloud SQL 基础设施工具的 Google Cloud 项目 IDuseClientOAuthboolean否为true时使用客户端侧 OAuth 授权,否则使用 Application Default Credentials(ADC),默认falsereadOnlyboolean否为true时抑制具备写能力的管理工具,默认falsesource 的两种认证方式在源码 cloud_sql_admin.go 的Initialize方法中实现:默认走 ADC(google.FindDefaultCredentials);当useClientOAuth为true时,每次请求由客户端(如 Web 浏览器)提供 OAuth 2.0 access token,并在GetService中用该 token 构造独立的sqladmin.Service实例。需要特别注意:创建实例属于写操作,若 source 设置了readOnly: true,该工具应被抑制。一个最小可用的 source 配置如下(摘自文档示例):kind: source name: my-cloud-sql-admin type: cloud-sql-admin工具配置示例文档给出的标准 YAML 配置如下,description字段完整描述了两个预设的行为,对 Agent 的决策有直接引导作用:kind: tool name: create-sql-instance type: cloud-sql-postgres-create-instance source: cloud-sql-admin-source description: Creates a Postgres instance using Production and Development presets. For the Development template, it chooses a 2 vCPU, 16 GiB RAM, 100 GiB SSD configuration with Non-HA/zonal availability. For the Production template, it chooses an 8 vCPU, 64 GiB RAM, 250 GiB SSD configuration with HA/regional availability. The Enterprise Plus edition is used in both cases. The default database version is POSTGRES_17. The agent should ask the user if they want to use a different version.工具配置参数(Tool Configuration)文档定义的工具配置字段如下:字段类型必填说明typestring是必须为cloud-sql-postgres-create-instancesourcestring是要使用的cloud-sql-adminsource 名称descriptionstring否工具描述从源码结构看(cloudsqlpgcreateinstances.go 的Config结构体),除了文档列出的三个字段外,还支持可选的annotations字段用于自定义工具注解。另外有两点源码级细节值得注意:默认描述回退:Initialize方法中,当description为空时会自动填充一段默认描述,内容与上文 YAML 示例中的description完全一致——也就是说文档示例中的描述其实就是源码内置的默认值,用户可省略该字段。破坏性注解:工具通过tools.NewDestructiveAnnotations标记为破坏性(destructive)工具,提示 Agent/用户该操作会产生真实的云资源。工具输入参数(Tool Inputs)文档定义的输入参数及源码中的默认值如下:参数类型必填默认值说明projectstring是若 source 配置了defaultProject则预填GCP 项目 IDnamestring是—实例名称databaseVersionstring否POSTGRES_17PostgreSQL 数据库版本,未指定时默认使用最新可用版本(如POSTGRES_17)rootPasswordstring是—实例 root 密码editionPresetstring否Development实例预设,取值为Production或Development,决定默认机型与可用性其中databaseVersion默认POSTGRES_17与editionPreset默认Development这两个默认值在源码buildParams函数中通过parameters.WithStringDefault注入,与文档描述一致。还有一个容易忽略但很实用的机制:当绑定的 source 配置了defaultProject时,project参数会被预填该值,且参数描述会变为 This is pre-configured; do not ask for it unless the user explicitly provides a different one(该值已预配置,除非用户显式提供不同值,否则不要向用户询问)。从源码结构看,这是通过resolveParams在工具解析阶段对比 source 的GetDefaultProject()动态生成的,目的是减少 Agent 在每次调用时的多余提问。预设机制:Production 与 Development 的映射关系editionPreset是本工具的核心设计——它把选机型、选可用性、选磁盘这一组决策收敛为单一参数。Invoke方法中的 switch 分支(大小写不敏感)定义了两种预设到sqladmin.Settings的精确映射:设置项ProductionDevelopmentAvailabilityTypeREGIONAL(HA,区域级)ZONAL(非 HA,可用区级)EditionENTERPRISE_PLUSENTERPRISE_PLUSTierdb-perf-optimized-N-8(8 vCPU)db-perf-optimized-N-2(2 vCPU)DataDiskSizeGb250GiB100GiBDataDiskTypePD_SSDPD_SSD这与工具描述中Production 为 8 vCPU / 64 GiB RAM / 250 GiB SSD / HA,Development 为 2 vCPU / 16 GiB RAM / 100 GiB SSD / 非 HA,两者均使用 Enterprise Plus 版的说明完全吻合(内存规格由db-perf-optimized-N-*机型隐式决定)。若传入其他取值,工具会返回 Agent 错误:invalid editionPreset: ... Must be either Production or Development。执行流程与底层 API 调用工具的调用链为:Invoke→ source 的CreateInstance→ Cloud SQL Admin API 的instances.insert。参数校验:Invoke从参数映射中逐一取出project、name、databaseVersion、rootPassword、editionPreset,任一缺失即返回util.NewAgentError。Agent 错误与常规服务错误语义不同,它指示 Agent 应补齐参数后重试,而不是把请求判为系统故障。构造实例对象:source 层的CreateInstance方法将参数组装为sqladmin.DatabaseInstance{Name, DatabaseVersion, RootPassword, Settings, Project},注意rootPassword仅在此创建阶段传入。发起请求:调用service.Instances.Insert(project, instance).Do(),即 Cloud SQL Admin API 的实例创建接口;请求发出后 Cloud SQL 返回一个Operation 资源(例如{name: op1, status: PENDING}),工具原样将该 operation 返回给调用方,真正的建实例过程是异步的。错误处理:API 错误经util.ProcessGcpError统一包装后返回。因此,完整的自动化建库工作流通常是:调用create_instance拿到 operation → 用同集成的cloud-sql-wait-for-operation工具轮询至完成 → 再用cloud-sql-create-database、cloud-sql-create-users等工具初始化库与账号。这些工具在仓库的预置配置 cloud-sql-postgres-admin.yaml 中已被组织进cloud_sql_postgres_admin_tools工具集:kind: source name: cloud-sql-admin-source type: cloud-sql-admin defaultProject: ${CLOUD_SQL_POSTGRES_PROJECT:} readOnly: ${CLOUD_SQL_POSTGRES_READONLY:false} --- kind: tool name: create_instance type: cloud-sql-postgres-create-instance source: cloud-sql-admin-source # ... 同文件还定义了 get_instance、list_instances、create_database、 # list_databases、create_user、wait_for_operation、clone_instance、 # postgres_upgrade_precheck、create_backup、restore_backup 等工具 --- kind: toolset name: cloud_sql_postgres_admin_tools tools: - create_instance # ... 以及上述其余工具可见预置配置通过defaultProject支持从环境变量CLOUD_SQL_POSTGRES_PROJECT注入默认项目、通过CLOUD_SQL_POSTGRES_READONLY控制只读模式,配合前文project 参数预填机制,部署后可实现零提问的项目绑定。集成测试验证仓库在 cloud_sql_pg_create_instances_test.go 中提供了端到端测试,用一个httptest假服务器把https://sqladmin.googleapis.com的请求劫持到本地,并逐字段断言请求体,验证了本文的关键论断:Production 用例:请求体断言AvailabilityType: REGIONAL、Edition: ENTERPRISE_PLUS、Tier: db-perf-optimized-N-8、DataDiskSizeGb: 250、DataDiskType: PD_SSD,与源码映射一致;Development 用例:断言ZONAL/db-perf-optimized-N-2/100GiB,且未传databaseVersion时请求体使用默认值POSTGRES_17(印证了默认值注入);缺参用例:仅传name时,API 返回{error:parameter \project\ is required};测试同时校验了请求User-Agent头必须携带genai-toolbox/标识。适用前提与注意事项该工具创建的是真实计费的 GCP 资源且被标记为破坏性工具,source 的readOnly开关、Agent 的确认机制是主要的防护手段;认证依赖 ADC 或客户端 OAuth,运行环境必须具备sqladmin相关 API 的访问凭据(见 source 文档);工具本身只负责发起创建并返回 operation,不等待实例就绪——轮询请配合cloud-sql-wait-for-operation工具完成;rootPassword为必填参数,创建完成后实例即以该密码提供postgres超级用户的访问;数据库版本默认POSTGRES_17,如需其他版本(如POSTGRES_15,测试用例即以此验证了显式传参路径)需显式传入databaseVersion。综合来看,这个工具的价值在于把 Cloud SQL 实例创建中最易出错的部分——机型选择、HA 可用性、磁盘规格的组合决策——固化为两个经过验证的预设,同时保留了databaseVersion等关键自由度,并通过预置defaultProject机制把 Agent 的交互成本降到最低。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考