在 GitHub Copilot 中启用 PostgreSQL DBA 智能体：基于 ms-ossdata.vscode-pgsql 扩展的数据库运维实战指南

本指南围绕 awesome-copilot 仓库中的 PostgreSQL Database Administrator 智能体 展开，它是一份让 GitHub Copilot 扮演专业 PostgreSQL 数据库管理员（DBA）的 Agent 定义文件。你将掌握该智能体的能力边界、15 个 pgsql_* 工具的具体用途、前置扩展安装校验流程，以及如何结合仓库内配套的插件与技能完成建库、SQL 调优、备份恢复、性能监控与安全加固等典型 DBA 工作。

智能体定位：让 Copilot 以 DBA 身份接管数据库操作

agents/postgresql-dba.agent.md 是一份遵循 awesome-copilot 仓库 Agent 规范的 Markdown 文件，通过 YAML front matter 声明元数据，再用自然语言定义角色行为。其核心定位十分明确：在 GitHub Copilot 的对话中，将模型引导为一名具备 PostgreSQL 管理专长的数据库管理员，且所有数据库交互都必须通过扩展提供的工具完成，而不是猜测或从代码库推断。

该文件的 front matter 如下（字段含义可直接对照 AGENTS.md 中“Agent Files”一节的约定）：

---
description: "Work with PostgreSQL databases using the PostgreSQL extension."
name: "PostgreSQL Database Administrator"
tools: ["codebase", "edit/editFiles", "githubRepo", "extensions", "runCommands",
        "database", "pgsql_bulkLoadCsv", "pgsql_connect", "pgsql_describeCsv",
        "pgsql_disconnect", "pgsql_listDatabases", "pgsql_listServers",
        "pgsql_modifyDatabase", "pgsql_open_script", "pgsql_query", "pgsql_visualizeSchema"]
---

• description：一段在安装、检索与模型选择时展示的简述，说明该智能体的用途是“通过 PostgreSQL 扩展操作数据库”。
• name：人类可读的名称 PostgreSQL Database Administrator（文件名仍遵循小写加连字符的 postgresql-dba 约定）。
• tools：显式声明智能体可调用的工具集合，其中 pgsql_* 系列即由下文提到的 PostgreSQL 扩展提供。

前置条件：先通过 #extensions 校验 ms-ossdata.vscode-pgsql

原文档正文的第一条指令即是一个强制前置检查：在任何工具调用之前，使用 #extensions 确认 ms-ossdata.vscode-pgsql 扩展已安装并启用。该扩展（PostgreSQL for Visual Studio Code）为智能体提供与 PostgreSQL 数据库交互所需的全部工具；若未安装，智能体必须暂停并请用户先行安装，而不是强行继续。

这一设计在 Agent 实践上有两点意义：

1. 能力可达性校验先行：Agent 声明的 pgsql_* 工具只有在扩展可用时才真实存在，先校验再执行可避免工具调用失败、幻觉式操作。
2. 环境依赖显式化：与仓库中同族的 MS SQL Database Administrator 相互呼应——后者同样要求先校验 ms-mssql.mssql 扩展（工具名为 mssql_*），可见“扩展驱动数据库能力”是该仓库数据库类 Agent 的通用模式。

15 个 pgsql 工具：Agent 操作 PostgreSQL 的完整工具箱

tools 字段中列出的工具即该智能体可用以“看见”和“修改”数据库的通道。结合工具命名可以还原其职责：

工具	职责推断
pgsql_connect	建立到 PostgreSQL 服务器的连接（会话入口）
pgsql_disconnect	关闭当前数据库连接（会话出口）
pgsql_listServers	枚举已配置的服务器/连接配置
pgsql_listDatabases	列出服务器上的数据库清单
pgsql_modifyDatabase	对数据库执行修改类操作（建库、改库等 DDL 层面操作）
pgsql_query	执行任意 SQL 查询/语句，是日常交互的核心工具
pgsql_bulkLoadCsv	批量将 CSV 数据导入数据库表
pgsql_describeCsv	解析并描述 CSV 文件结构，为导入前检查做准备
pgsql_open_script	在编辑器中打开 SQL 脚本（便于审阅与后续执行）
pgsql_visualizeSchema	可视化展示数据库 schema 结构
codebase / edit/editFiles / githubRepo	代码库检索、文件编辑与仓库访问（辅助上下文）
extensions	扩展管理，用于前置校验 ms-ossdata.vscode-pgsql
runCommands / database	运行终端命令与数据库相关通用能力

从结构上看，这一工具集覆盖了一条完整的 DBA 操作链路：连接 → 枚举服务器/数据库 → 执行查询 → 批量导入数据 → 可视化 schema → 断开，足以支撑绝大多数日常运维场景。

智能体的五大核心职责域

原文档将 DBA 角色职责归纳为五个方面，这是智能体在对话中被期望优先覆盖的能力范围：

1. 创建和管理数据库（Creating and managing databases）：通过 pgsql_modifyDatabase、pgsql_query 完成建库、表结构维护、角色权限配置等。
2. 编写与优化 SQL 查询（Writing and optimizing SQL queries）：编写查询，并结合 EXPLAIN ANALYZE、索引策略等手段做性能优化。
3. 执行数据库备份与恢复（Performing database backups and restores）：规划与执行备份恢复流程。
4. 监控数据库性能（Monitoring database performance）：观察连接状态、慢查询、缓存命中率等运行指标。
5. 实施安全措施（Implementing security measures）：落实权限最小化、行级安全（RLS）、连接安全等防护。

这五项职责与本仓库配套技能高度契合：例如 postgresql-optimization 技能 中的 pg_stat_activity 连接监控、pg_stat_statements 慢查询定位，以及 postgresql-code-review 技能 中的 RLS 策略与细粒度授权示例，都可在 Agent 执行上述职责时作为即时参考。

铁律：始终用工具检查数据库，而非翻阅代码库

原文档以强调语气写下了最重要的一条行为约束：“Always use the tools to inspect the database, do not look into the codebase.”（始终使用工具检查数据库，不要查看代码库）。

这条规则是数据库 Agent 与通用编码 Agent 的本质区别：数据库的真实状态只能通过 pgsql_query、pgsql_listDatabases 等工具从运行中的实例获取，代码库中的 schema 定义、迁移脚本都可能与生产库存在漂移。因此智能体在任何判断（表是否存在、数据长什么样、慢查询在哪）之前，都应先发起真实工具调用，用数据库本身作为唯一事实来源——这从机制上杜绝了基于陈旧或错误上下文做出的“猜测式运维”。

安装、激活与使用方式

依据 docs/README.agents.md 中“How to Use Custom Agents”一节，启用该智能体的标准流程为：

1. 安装 Agent 文件：将 agents/postgresql-dba.agent.md 下载并放入你的仓库（或直接使用 VS Code 的一键安装入口）。
2. 配置扩展环境：在 VS Code 中安装并启用 ms-ossdata.vscode-pgsql 扩展，按需配置服务器连接信息。
3. 激活使用：通过 VS Code Chat 界面选择该 Agent（或将其分配给 CCA），之后即可直接以自然语言下达 DBA 任务，例如“列出当前实例的所有数据库”“分析这张表的查询为什么慢”“帮我把这份 CSV 导入 orders 表”。

激活后，Agent 会自动完成前置校验——若扩展缺失会主动提示你先安装，避免后续工具全部失效。

配套资源：插件打包与同族技能

该智能体并非孤立存在，而是被打包进 database-data-management 插件。见 plugins/database-data-management/README.md：

• 插件可通过 Copilot CLI 安装：copilot plugin install database-data-management@awesome-copilot
• 插件同时打包了两个数据库 Agent：postgresql-dba（本文主角）与 ms-sql-dba
• 插件还附带四个 slash command 技能：sql-optimization、sql-code-review、postgresql-optimization、postgresql-code-review

其中两个 PostgreSQL 专项技能可作为 DBA 智能体的“知识弹药库”：

• postgresql-optimization/SKILL.md：覆盖 JSONB 与 GIN 索引、数组操作、窗口函数、全文检索、范围/几何类型、扩展生态（uuid-ossp、pgcrypto、pg_trgm、btree_gin）、EXPLAIN (ANALYZE, BUFFERS) 调优、游标分页等 PostgreSQL 专有能力。
• postgresql-code-review/SKILL.md：聚焦 PostgreSQL 专属的质量审查标准，包括 JSONB 查询模式（@> 包含操作符）、CITEXT/ENUM/DOMAIN 数据类型选型、触发器函数优化、扩展使用规范、RLS 行级安全与细粒度授权（GRANT SELECT, INSERT, UPDATE ...）。

一个典型的“建库 + 导入 + 优化 + 加固”链路可完整映射到上述资源：用 pgsql_connect/pgsql_modifyDatabase 建库建表 → 用 pgsql_describeCsv + pgsql_bulkLoadCsv 导入数据 → 用 pgsql_query 跑 EXPLAIN ANALYZE 并按优化技能补索引 → 按代码审查技能启用 RLS 与最小权限。

小结

agents/postgresql-dba.agent.md 用极简的 Agent 定义，勾勒出一个“工具驱动、数据库为唯一事实源”的 PostgreSQL DBA 智能体：以 #extensions 校验 ms-ossdata.vscode-pgsql 为前置，以 15 个 pgsql_* 工具为双手，以建库、SQL 优化、备份恢复、性能监控、安全加固五大职责为边界。配合仓库内的 database-data-management 插件与 postgresql-optimization、postgresql-code-review 两项技能，你可以快速组装出一套在 GitHub Copilot 内完成 PostgreSQL 日常运维的完整工作流。