实战详解)
MCP Toolbox for Databases:Cloud SQL for PostgreSQL 预构建配置(cloud-sql-postgres)实战详解【免费下载链接】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 for PostgreSQL 的预构建配置cloud-sql-postgres展开,完整覆盖其环境变量、权限要求与内置工具清单,并结合仓库源码剖析预构建配置的加载机制、cloud-sql-postgres数据源的连接认证逻辑(IAM / 密码双模式)以及只读会话的实现细节,帮助你在不手写任何tools.yaml的前提下,快速为 AI Agent 接入 Cloud SQL PostgreSQL 实例并提供查询、诊断、实例管理与监控能力。一、预构建配置与--prebuilt启动方式在 预构建配置文档 中,Cloud SQL for PostgreSQL 对应的--prebuilt取值为cloud-sql-postgres。所谓预构建配置(prebuilt config),是指内置在 Toolbox 二进制中的、按数据源类型预定义的 Source Tool 组合:使用--prebuilt cloud-sql-postgres启动后,无需准备自定义配置文件即可直接服务。从源码结构看,这一机制的实现链路是:预构建配置加载器 通过//go:embed tools/*.yaml将 internal/prebuiltconfigs/tools/ 目录下的全部 YAML 嵌入二进制,并在init()阶段解析为文件名(去 .yaml) - 配置内容的映射。因此cloud-sql-postgres.yaml对应的--prebuilt值就是cloud-sql-postgres;--prebuilt命令行标志 的 help 文案会动态列出当前二进制中所有可用的预构建源(prebuiltconfigs.GetPrebuiltSources()),该标志可重复指定多次;启动选项解析逻辑 在检测到使用预构建配置时,会打印Using prebuilt tool configurations for: ...,并输出一条重要的安全警告:这些预构建配置面向 build-time(构建期)使用场景……对可能不受信任的开发者而言安全强度不足,即官方建议预构建配置用于可信开发场景,生产运行时应改用最小权限的自定义配置;--prebuilt支持源/工具集语法(如cloud-sql-postgres/monitor),此时只暴露该预构建配置中指定 group 内的工具;若工具集名不存在,报错会列出所有可用的 toolset 名称。典型的启动方式(配合下文环境变量)如下:export CLOUD_SQL_POSTGRES_PROJECTmy-gcp-project export CLOUD_SQL_POSTGRES_REGIONus-central1 export CLOUD_SQL_POSTGRES_INSTANCEmy-pg-instance export CLOUD_SQL_POSTGRES_DATABASEmydb toolbox serve --prebuilt cloud-sql-postgres --port 8080若只想要某个子集,例如监控诊断工具:toolbox serve --prebuilt cloud-sql-postgres/monitor --port 8080二、环境变量配置参数该预构建配置通过以下环境变量完成全部参数化。对照 internal/prebuiltconfigs/tools/cloud-sql-postgres.yaml 可以看到,每个${VAR}占位符在解析时替换为环境变量取值,${VAR:default}语法提供默认值:环境变量必填说明YAML 映射CLOUD_SQL_POSTGRES_PROJECT是GCP 项目 IDproject: ${CLOUD_SQL_POSTGRES_PROJECT}CLOUD_SQL_POSTGRES_REGION是Cloud SQL 实例所在区域region: ${CLOUD_SQL_POSTGRES_REGION}CLOUD_SQL_POSTGRES_INSTANCE是Cloud SQL 实例 IDinstance: ${CLOUD_SQL_POSTGRES_INSTANCE}CLOUD_SQL_POSTGRES_DATABASE是要连接的数据库名database: ${CLOUD_SQL_POSTGRES_DATABASE}CLOUD_SQL_POSTGRES_USER否数据库用户名;不填时默认使用 IAM 认证user: ${CLOUD_SQL_POSTGRES_USER:}CLOUD_SQL_POSTGRES_PASSWORD否数据库用户密码;不填时默认使用 IAM 认证password: ${CLOUD_SQL_POSTGRES_PASSWORD:}CLOUD_SQL_POSTGRES_IP_TYPE否IP 类型,Public或Private,默认PublicipType: ${CLOUD_SQL_POSTGRES_IP_TYPE:public}CLOUD_SQL_POSTGRES_READONLY否设为true时在数据库会话级别强制只读(cloudsql_session_read_onlylocked)并抑制写入类工具,默认falsereadOnly: ${CLOUD_SQL_POSTGRES_READONLY:false}同样的CLOUD_SQL_POSTGRES_READONLY值还会被注入到配置中的cloud-sql-admin源,使实例管理类工具(备份、克隆等)同步受到只读约束。认证模式:IAM 与密码二选一数据源连接实现 中的getConnectionConfig函数决定了实际的认证行为,可以归纳为三种分支:user 与 password 同时提供:使用密码认证,DSN 形如user%s password%s dbname%s sslmodedisable application_name%s,不走 IAM;user 为空:从应用默认凭据(ADC)中提取调用者邮箱作为 IAM 主体,以 IAM 数据库用户身份连接;仅提供 user(无密码):以该用户名作为 IAM 主体连接。若提供了密码却没有用户名,会直接报错要求两者都填或都不填。此外,连接池初始化时会先Ping再执行SELECT 1双重校验,任何一步失败都会关闭连接池并返回错误,保证服务启动即完成端到端连通性验证。只读模式的实现细节readOnly为true时,实现上会在 DSN 末尾追加options-c cloudsql_session_read_onlylocked。源码注释特别强调必须使用下划线形式(cloudsql_session_read_only)而非点号形式:PostgreSQL 会把带点的 GUC 当作自定义占位符静默忽略,导致会话实际仍处于可读写状态。这与文档中在数据库会话级别强制只读执行的描述一致,同时 Toolbox 层面还会抑制写入类工具,形成双层防护。三、权限要求使用此预构建配置需要两类权限:Cloud SQL Client(roles/cloudsql.client):用于通过 Cloud SQL Connector 连接实例;数据库级别权限(如SELECT、INSERT等):用于执行具体查询。只读诊断类工具通常只需SELECT;而execute_sql、备份/恢复等工具则需要相应的写权限或更高的项目级角色(如roles/cloudsql.admin)。四、内置工具全览文档列出的 32 个工具全部来自cloud-sql-postgres数据源,底层复用 PostgreSQL 通用工具类型。按功能域分组(部分工具在 预构建 YAML 中给出了精确的 SQL 实现与描述,此处一并补充):数据访问与探查execute_sql:执行单条 SQL 语句(postgres-execute-sql);list_tables:以 JSON 形式列出用户自建表(普通表或分区表)的详细 schema 信息(对象类型、列、约束、索引、触发器、属主、注释),支持按逗号分隔的表名过滤,省略则列出所有用户 schema 中的表;list_views:列出pg_views中的视图,默认 50 行,返回 schemaname、viewname、ownername;list_schemas:列出数据库中的 schema;list_triggers:列出触发器;list_indexes:列出用户自建索引;list_sequences:列出序列;list_stored_procedure:列出存储过程;list_publication_tables:列出逻辑复制发布(logical publication)中的表;list_tablespaces:列出表空间;list_roles:列出所有用户创建的角色。性能诊断与运维list_active_queries:从pg_stat_activity中按运行时长降序列出当前运行中的查询(默认 Top 50),返回 pid、用户、库名、application_name、客户端地址、状态、等待事件、开始时间与 SQL 文本;long_running_transactions:列出超过指定时长的事务,输出含进程 ID、连接/事务/查询持续时间、等待事件与 SQL;list_locks:列出活动进程持有的锁,聚合展示每个进程关联的锁(关系、模式、是否已授予);replication_stats:列出每个副本的进程 ID、backend_xmin、连接状态、sync_state以及 sent/write/flush/replay 各阶段延迟字节数与总延迟;list_replication_slots:列出所有复制槽的关键信息(类型、库名、是否活动、restart_lsn 等),并用pg_wal_lsn_diff计算被槽阻止清理的未回收 WAL 大小;get_query_plan:对单条语句生成EXPLAIN (FORMAT JSON)执行计划而不真正执行。YAML 描述中明确提醒:该工具将用户输入直接拼入EXPLAIN (FORMAT JSON) {{.query}}模板,存在 SQL 注入风险,不宜在生产环境直接暴露;list_query_stats、list_table_stats、list_database_stats:查询统计、表统计与库级关键性能/活动统计;get_column_cardinality:获取列基数(用于分析索引选择性);database_overview:一次性获取 PostgreSQL 服务器当前状态概览。存储健康与引擎配置list_top_bloated_tables:按死元组数量列出 Top 表(YAML 中实现为pg_stat_user_tables查询,返回 schema、表名、live/dead 元组数、死元组百分比、最近 vacuum/analyze 时间,limit参数默认 50);list_invalid_indexes:列出所有无效索引(indisvalid FALSE),它们通常由失败的CREATE INDEX CONCURRENTLY产生,占据磁盘但无法被查询规划器使用;list_autovacuum_configurations/list_memory_configurations:分别从pg_settings中列出 Autovacuum 类配置与内存相关配置(work_mem、maintenance_work_mem、shared_buffers等,并用pg_size_pretty美化输出);list_pg_settings:列出服务器全部配置参数;list_available_extensions/list_installed_extensions:发现可安装的扩展(名称、默认版本、描述)与已安装扩展(名称、版本、schema、属主)。实例管理、备份与监控(同一预构建配置中的补充工具)当前仓库中的 cloud-sql-postgres.yaml 除上述工具外,还额外注册了cloud-sql-admin-source与cloud-monitoring-source两个源,并提供:实例与库管理:create_instance、get_instance、list_instances、clone_instance、create_database、list_databases、create_user、wait_for_operation(超时倍增系数 4);备份与升级:create_backup、restore_backup、postgres_upgrade_precheck(大版本升级兼容性检查);Cloud Monitoring 指标:get_system_metrics与get_query_metrics,两者均以 PromQL 查询 Cloud Monitoring 时间序列数据——前者面向系统级指标(CPU 利用率、连接数、磁盘读写、死锁计数、复制延迟、事务 ID 使用率等 26 项指标在描述中逐一列出),后者面向 Query Insights 的聚合/按查询/按标签三类查询指标(执行时间、IO 时间、锁等待、行计数、共享块访问等);Vector Assist:define_spec、modify_spec、apply_spec、generate_query、improve_query_recall、list_specs、get_spec、delete_spec,用于声明式地定义并管理向量检索工作负载(规格),详见 Vector Assist 工具文档目录。五、工具集(Toolset Groups)预构建 YAML 末尾定义了 8 个 group,可配合--prebuilt cloud-sql-postgres/group语法按需暴露:工具集定位包含工具admin实例供给:新建实例、建库建用户、克隆环境、跟踪长时操作create_instance、get_instance、list_instances、create_database、list_databases、create_user、wait_for_operation、clone_instancelifecycle生命周期:备份恢复、大版本升级检查、状态监控create_backup、restore_backup、postgres_upgrade_precheck、wait_for_operation、database_overview、get_instance、list_instancesdata探查 schema 对象与执行自定义 SQLexecute_sql、list_tables、list_views、list_schemas、list_triggers、list_indexes、list_sequences、list_stored_proceduremonitor性能排障:执行计划、资源占用进程、PromQL 系统指标get_system_metrics、get_query_metrics、list_query_stats、get_query_plan、list_database_stats、list_active_queries、long_running_transactions、list_lockshealth健康审计:存储膨胀、无效索引、表统计、autovacuum 配置list_top_bloated_tables、list_invalid_indexes、list_table_stats、get_column_cardinality、list_autovacuum_configurations、list_tablespaces、database_overview、list_pg_settingsview-config扩展发现与引擎级参数微调(内存、服务器配置)list_available_extensions、list_installed_extensions、list_memory_configurations、list_pg_settings、database_overview、get_instancereplication复制健康与角色/安全审计replication_stats、list_replication_slots、list_publication_tables、list_roles、list_pg_settings、database_overviewvectorassist以意图驱动方式搭建与调优向量工作负载execute_sql、define_spec、modify_spec、apply_spec、generate_query、improve_query_recall、list_specs、get_spec、delete_spec例如只暴露健康审计工具:toolbox serve --prebuilt cloud-sql-postgres/health。六、连接链路:Cloud SQL Go Connector 与 pgx 连接池从 数据源实现 看,cloud-sql-postgres源在初始化时:以默认IPType: public构造Config结构(所有连接必需字段带validate:required校验);由project、region、instance拼出实例连接名project:region:instance,并通过cloudsqlconn.NewDialer创建 Cloud SQL Go Connector 拨号器;将拨号器注入pgxpool的DialFunc,由 Cloud SQL 数据库文档页 描述的 source 配置(含sqlCommenter开关,可在查询前缀中注入 sqlcommenter 注释)共同决定连接行为;RunSQL执行时会按配置为语句前置 sqlcommenter 注释,并将结果行以有序键值行(orderedmap.Row)返回,统一归一化各列类型。ipType取值public/private对应实例的公网/私网 IP 接入;私网部署时需确保 Toolbox 运行环境与实例处于同一 VPC 网络可达范围内。七、使用建议与限制适用前提:预构建配置面向可信的构建期场景(开发者本地、CI 中的 Agent 辅助开发)。启动逻辑 会显式警告其不适用于直接对接不受信任调用方的运行时场景;生产环境建议基于相同 source 类型手写最小工具集的自定义配置;最小暴露面:优先用--prebuilt cloud-sql-postgres/group或CLOUD_SQL_POSTGRES_READONLYtrue收敛写能力;只读模式下cloud-sql-admin源同样受约束;慎用get_query_plan:其模板直接拼接用户 SQL,描述中自述存在 SQL 注入风险,不适合直接暴露给不可信输入;认证选择:默认 IAM 认证要求运行环境具备 ADC(应用默认凭据)与roles/cloudsql.client;改用密码认证则必须同时提供用户名与密码;配置与测试依据:预构建配置的加载与展开逻辑可通过 prebuiltconfigs 单元测试 与 cmd 层配置解析测试 对照验证;Cloud SQL PostgreSQL 的实例管理、升级检查与 Vector Assist 行为另有 集成测试 覆盖。【免费下载链接】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 for PostgreSQL 预构建配置(cloud-sql-postgres)实战详解
MCP Toolbox for Databases:Cloud SQL for PostgreSQL 预构建配置(cloud-sql-postgres)实战详解【免费下载链接】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 for PostgreSQL 的预构建配置cloud-sql-postgres展开,完整覆盖其环境变量、权限要求与内置工具清单,并结合仓库源码剖析预构建配置的加载机制、cloud-sql-postgres数据源的连接认证逻辑(IAM / 密码双模式)以及只读会话的实现细节,帮助你在不手写任何tools.yaml的前提下,快速为 AI Agent 接入 Cloud SQL PostgreSQL 实例并提供查询、诊断、实例管理与监控能力。一、预构建配置与--prebuilt启动方式在 预构建配置文档 中,Cloud SQL for PostgreSQL 对应的--prebuilt取值为cloud-sql-postgres。所谓预构建配置(prebuilt config),是指内置在 Toolbox 二进制中的、按数据源类型预定义的 Source Tool 组合:使用--prebuilt cloud-sql-postgres启动后,无需准备自定义配置文件即可直接服务。从源码结构看,这一机制的实现链路是:预构建配置加载器 通过//go:embed tools/*.yaml将 internal/prebuiltconfigs/tools/ 目录下的全部 YAML 嵌入二进制,并在init()阶段解析为文件名(去 .yaml) - 配置内容的映射。因此cloud-sql-postgres.yaml对应的--prebuilt值就是cloud-sql-postgres;--prebuilt命令行标志 的 help 文案会动态列出当前二进制中所有可用的预构建源(prebuiltconfigs.GetPrebuiltSources()),该标志可重复指定多次;启动选项解析逻辑 在检测到使用预构建配置时,会打印Using prebuilt tool configurations for: ...,并输出一条重要的安全警告:这些预构建配置面向 build-time(构建期)使用场景……对可能不受信任的开发者而言安全强度不足,即官方建议预构建配置用于可信开发场景,生产运行时应改用最小权限的自定义配置;--prebuilt支持源/工具集语法(如cloud-sql-postgres/monitor),此时只暴露该预构建配置中指定 group 内的工具;若工具集名不存在,报错会列出所有可用的 toolset 名称。典型的启动方式(配合下文环境变量)如下:export CLOUD_SQL_POSTGRES_PROJECTmy-gcp-project export CLOUD_SQL_POSTGRES_REGIONus-central1 export CLOUD_SQL_POSTGRES_INSTANCEmy-pg-instance export CLOUD_SQL_POSTGRES_DATABASEmydb toolbox serve --prebuilt cloud-sql-postgres --port 8080若只想要某个子集,例如监控诊断工具:toolbox serve --prebuilt cloud-sql-postgres/monitor --port 8080二、环境变量配置参数该预构建配置通过以下环境变量完成全部参数化。对照 internal/prebuiltconfigs/tools/cloud-sql-postgres.yaml 可以看到,每个${VAR}占位符在解析时替换为环境变量取值,${VAR:default}语法提供默认值:环境变量必填说明YAML 映射CLOUD_SQL_POSTGRES_PROJECT是GCP 项目 IDproject: ${CLOUD_SQL_POSTGRES_PROJECT}CLOUD_SQL_POSTGRES_REGION是Cloud SQL 实例所在区域region: ${CLOUD_SQL_POSTGRES_REGION}CLOUD_SQL_POSTGRES_INSTANCE是Cloud SQL 实例 IDinstance: ${CLOUD_SQL_POSTGRES_INSTANCE}CLOUD_SQL_POSTGRES_DATABASE是要连接的数据库名database: ${CLOUD_SQL_POSTGRES_DATABASE}CLOUD_SQL_POSTGRES_USER否数据库用户名;不填时默认使用 IAM 认证user: ${CLOUD_SQL_POSTGRES_USER:}CLOUD_SQL_POSTGRES_PASSWORD否数据库用户密码;不填时默认使用 IAM 认证password: ${CLOUD_SQL_POSTGRES_PASSWORD:}CLOUD_SQL_POSTGRES_IP_TYPE否IP 类型,Public或Private,默认PublicipType: ${CLOUD_SQL_POSTGRES_IP_TYPE:public}CLOUD_SQL_POSTGRES_READONLY否设为true时在数据库会话级别强制只读(cloudsql_session_read_onlylocked)并抑制写入类工具,默认falsereadOnly: ${CLOUD_SQL_POSTGRES_READONLY:false}同样的CLOUD_SQL_POSTGRES_READONLY值还会被注入到配置中的cloud-sql-admin源,使实例管理类工具(备份、克隆等)同步受到只读约束。认证模式:IAM 与密码二选一数据源连接实现 中的getConnectionConfig函数决定了实际的认证行为,可以归纳为三种分支:user 与 password 同时提供:使用密码认证,DSN 形如user%s password%s dbname%s sslmodedisable application_name%s,不走 IAM;user 为空:从应用默认凭据(ADC)中提取调用者邮箱作为 IAM 主体,以 IAM 数据库用户身份连接;仅提供 user(无密码):以该用户名作为 IAM 主体连接。若提供了密码却没有用户名,会直接报错要求两者都填或都不填。此外,连接池初始化时会先Ping再执行SELECT 1双重校验,任何一步失败都会关闭连接池并返回错误,保证服务启动即完成端到端连通性验证。只读模式的实现细节readOnly为true时,实现上会在 DSN 末尾追加options-c cloudsql_session_read_onlylocked。源码注释特别强调必须使用下划线形式(cloudsql_session_read_only)而非点号形式:PostgreSQL 会把带点的 GUC 当作自定义占位符静默忽略,导致会话实际仍处于可读写状态。这与文档中在数据库会话级别强制只读执行的描述一致,同时 Toolbox 层面还会抑制写入类工具,形成双层防护。三、权限要求使用此预构建配置需要两类权限:Cloud SQL Client(roles/cloudsql.client):用于通过 Cloud SQL Connector 连接实例;数据库级别权限(如SELECT、INSERT等):用于执行具体查询。只读诊断类工具通常只需SELECT;而execute_sql、备份/恢复等工具则需要相应的写权限或更高的项目级角色(如roles/cloudsql.admin)。四、内置工具全览文档列出的 32 个工具全部来自cloud-sql-postgres数据源,底层复用 PostgreSQL 通用工具类型。按功能域分组(部分工具在 预构建 YAML 中给出了精确的 SQL 实现与描述,此处一并补充):数据访问与探查execute_sql:执行单条 SQL 语句(postgres-execute-sql);list_tables:以 JSON 形式列出用户自建表(普通表或分区表)的详细 schema 信息(对象类型、列、约束、索引、触发器、属主、注释),支持按逗号分隔的表名过滤,省略则列出所有用户 schema 中的表;list_views:列出pg_views中的视图,默认 50 行,返回 schemaname、viewname、ownername;list_schemas:列出数据库中的 schema;list_triggers:列出触发器;list_indexes:列出用户自建索引;list_sequences:列出序列;list_stored_procedure:列出存储过程;list_publication_tables:列出逻辑复制发布(logical publication)中的表;list_tablespaces:列出表空间;list_roles:列出所有用户创建的角色。性能诊断与运维list_active_queries:从pg_stat_activity中按运行时长降序列出当前运行中的查询(默认 Top 50),返回 pid、用户、库名、application_name、客户端地址、状态、等待事件、开始时间与 SQL 文本;long_running_transactions:列出超过指定时长的事务,输出含进程 ID、连接/事务/查询持续时间、等待事件与 SQL;list_locks:列出活动进程持有的锁,聚合展示每个进程关联的锁(关系、模式、是否已授予);replication_stats:列出每个副本的进程 ID、backend_xmin、连接状态、sync_state以及 sent/write/flush/replay 各阶段延迟字节数与总延迟;list_replication_slots:列出所有复制槽的关键信息(类型、库名、是否活动、restart_lsn 等),并用pg_wal_lsn_diff计算被槽阻止清理的未回收 WAL 大小;get_query_plan:对单条语句生成EXPLAIN (FORMAT JSON)执行计划而不真正执行。YAML 描述中明确提醒:该工具将用户输入直接拼入EXPLAIN (FORMAT JSON) {{.query}}模板,存在 SQL 注入风险,不宜在生产环境直接暴露;list_query_stats、list_table_stats、list_database_stats:查询统计、表统计与库级关键性能/活动统计;get_column_cardinality:获取列基数(用于分析索引选择性);database_overview:一次性获取 PostgreSQL 服务器当前状态概览。存储健康与引擎配置list_top_bloated_tables:按死元组数量列出 Top 表(YAML 中实现为pg_stat_user_tables查询,返回 schema、表名、live/dead 元组数、死元组百分比、最近 vacuum/analyze 时间,limit参数默认 50);list_invalid_indexes:列出所有无效索引(indisvalid FALSE),它们通常由失败的CREATE INDEX CONCURRENTLY产生,占据磁盘但无法被查询规划器使用;list_autovacuum_configurations/list_memory_configurations:分别从pg_settings中列出 Autovacuum 类配置与内存相关配置(work_mem、maintenance_work_mem、shared_buffers等,并用pg_size_pretty美化输出);list_pg_settings:列出服务器全部配置参数;list_available_extensions/list_installed_extensions:发现可安装的扩展(名称、默认版本、描述)与已安装扩展(名称、版本、schema、属主)。实例管理、备份与监控(同一预构建配置中的补充工具)当前仓库中的 cloud-sql-postgres.yaml 除上述工具外,还额外注册了cloud-sql-admin-source与cloud-monitoring-source两个源,并提供:实例与库管理:create_instance、get_instance、list_instances、clone_instance、create_database、list_databases、create_user、wait_for_operation(超时倍增系数 4);备份与升级:create_backup、restore_backup、postgres_upgrade_precheck(大版本升级兼容性检查);Cloud Monitoring 指标:get_system_metrics与get_query_metrics,两者均以 PromQL 查询 Cloud Monitoring 时间序列数据——前者面向系统级指标(CPU 利用率、连接数、磁盘读写、死锁计数、复制延迟、事务 ID 使用率等 26 项指标在描述中逐一列出),后者面向 Query Insights 的聚合/按查询/按标签三类查询指标(执行时间、IO 时间、锁等待、行计数、共享块访问等);Vector Assist:define_spec、modify_spec、apply_spec、generate_query、improve_query_recall、list_specs、get_spec、delete_spec,用于声明式地定义并管理向量检索工作负载(规格),详见 Vector Assist 工具文档目录。五、工具集(Toolset Groups)预构建 YAML 末尾定义了 8 个 group,可配合--prebuilt cloud-sql-postgres/group语法按需暴露:工具集定位包含工具admin实例供给:新建实例、建库建用户、克隆环境、跟踪长时操作create_instance、get_instance、list_instances、create_database、list_databases、create_user、wait_for_operation、clone_instancelifecycle生命周期:备份恢复、大版本升级检查、状态监控create_backup、restore_backup、postgres_upgrade_precheck、wait_for_operation、database_overview、get_instance、list_instancesdata探查 schema 对象与执行自定义 SQLexecute_sql、list_tables、list_views、list_schemas、list_triggers、list_indexes、list_sequences、list_stored_proceduremonitor性能排障:执行计划、资源占用进程、PromQL 系统指标get_system_metrics、get_query_metrics、list_query_stats、get_query_plan、list_database_stats、list_active_queries、long_running_transactions、list_lockshealth健康审计:存储膨胀、无效索引、表统计、autovacuum 配置list_top_bloated_tables、list_invalid_indexes、list_table_stats、get_column_cardinality、list_autovacuum_configurations、list_tablespaces、database_overview、list_pg_settingsview-config扩展发现与引擎级参数微调(内存、服务器配置)list_available_extensions、list_installed_extensions、list_memory_configurations、list_pg_settings、database_overview、get_instancereplication复制健康与角色/安全审计replication_stats、list_replication_slots、list_publication_tables、list_roles、list_pg_settings、database_overviewvectorassist以意图驱动方式搭建与调优向量工作负载execute_sql、define_spec、modify_spec、apply_spec、generate_query、improve_query_recall、list_specs、get_spec、delete_spec例如只暴露健康审计工具:toolbox serve --prebuilt cloud-sql-postgres/health。六、连接链路:Cloud SQL Go Connector 与 pgx 连接池从 数据源实现 看,cloud-sql-postgres源在初始化时:以默认IPType: public构造Config结构(所有连接必需字段带validate:required校验);由project、region、instance拼出实例连接名project:region:instance,并通过cloudsqlconn.NewDialer创建 Cloud SQL Go Connector 拨号器;将拨号器注入pgxpool的DialFunc,由 Cloud SQL 数据库文档页 描述的 source 配置(含sqlCommenter开关,可在查询前缀中注入 sqlcommenter 注释)共同决定连接行为;RunSQL执行时会按配置为语句前置 sqlcommenter 注释,并将结果行以有序键值行(orderedmap.Row)返回,统一归一化各列类型。ipType取值public/private对应实例的公网/私网 IP 接入;私网部署时需确保 Toolbox 运行环境与实例处于同一 VPC 网络可达范围内。七、使用建议与限制适用前提:预构建配置面向可信的构建期场景(开发者本地、CI 中的 Agent 辅助开发)。启动逻辑 会显式警告其不适用于直接对接不受信任调用方的运行时场景;生产环境建议基于相同 source 类型手写最小工具集的自定义配置;最小暴露面:优先用--prebuilt cloud-sql-postgres/group或CLOUD_SQL_POSTGRES_READONLYtrue收敛写能力;只读模式下cloud-sql-admin源同样受约束;慎用get_query_plan:其模板直接拼接用户 SQL,描述中自述存在 SQL 注入风险,不适合直接暴露给不可信输入;认证选择:默认 IAM 认证要求运行环境具备 ADC(应用默认凭据)与roles/cloudsql.client;改用密码认证则必须同时提供用户名与密码;配置与测试依据:预构建配置的加载与展开逻辑可通过 prebuiltconfigs 单元测试 与 cmd 层配置解析测试 对照验证;Cloud SQL PostgreSQL 的实例管理、升级检查与 Vector Assist 行为另有 集成测试 覆盖。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考