pg_ai_query：用自然语言在 PostgreSQL 里写 SQL

场景切入：再也不用死记硬背 JOIN 语法了

凌晨两点，你盯着屏幕里一张从未见过的数据表，需求是"找出所有在过去90天内有购买记录但最近30天没有活跃的客户"。脑子里疯狂组合 JOIN、WHERE、DATE_SUB……三分钟后，你终于拼出了一条语句，结果报错了。

现在想象一个完全不同的画面：你在 PostgreSQL 控制台里敲下 SELECT generate_query('find customers who made purchases in the last 90 days but have been inactive for the last 30 days');，回车，一条精准的 SQL 直接输出，还附带自然语言解释和性能警告——整个过程不过两秒。

这就是 pg_ai_query 正在做的事：把自然语言直接翻译成 PostgreSQL SQL，让数据库查询变成一件任何人都能做的事。

背景故事：一个 DBA 的效率革命

pg_ai_query 由独立开发者 benodiwal 创建，首次发布于 2025 年 11 月，2026 年初推出 v0.1.0 稳定版。这是一个典型的"刀锋工具"——目标用户极其明确，解决痛点极其具体：每天要和 SQL 打交道、但对复杂查询语法总是不够熟悉的开发者。

它被 PostgreSQL 官方博客收录推荐，并被收录进 PIGSTY（知名 PostgreSQL 一站式运维平台）的扩展库，IvorySQL 官方文档也集成了 pg_ai_query 的说明。与此同时，Zeabur 等云平台提供了预装了 pg_ai_query 的 PostgreSQL 容器镜像，进一步降低了上手门槛。

技术原理：LLM 如何理解你的数据库结构

pg_ai_query 不是简单地把自然语言扔给 GPT，然后祈祷它返回正确结果。它的核心是一个精心设计的"Schema-Aware"流水线：

第一步：自动发现数据库结构。 调用 get_database_tables() 和 get_table_details()，通过 PostgreSQL 的 SPI（Server Programming Interface）接口查询当前数据库的表结构、列类型、约束条件。这些信息被整理成结构化的 JSON 描述，连同用户输入的自然语言问题一起发送给 LLM。

第二步：构造结构化提示词。 系统内置了严格的 Prompt 模板，明确告诉 AI："你是一个资深 PostgreSQL 数据库分析师，你只能使用用户提供 schema 中存在的表和列"。Prompt 里预置了大量约束规则——防止 SELECT 变成 DELETE、要求所有 SQL 单行输出、强制加 LIMIT、要求返回 JSON 结构化响应。

第三步：调用 LLM 并解析响应。 支持 OpenAI GPT-4o 系列、Anthropic Claude 3.5/4.5 系列、Google Gemini 系列。LLM 返回 JSON 格式的响应，包含 sql、explanation、warnings、suggested_visualization 等字段。

第四步：格式化输出。 支持三种输出格式：纯 SQL、SQL+自然语言注释、完整 JSON。系统会自动给查询加 LIMIT（默认 1000 行），防止意外全表扫描。

核心功能：从自然语言生成到性能分析

generate_query() 是最常用的函数，输入自然语言，返回 SQL：

SELECT generate_query('monthly sales trend for the last year by category');

explain_query() 是另一个杀手级功能。它不是生成 SQL，而是分析已有的 SQL：先用 EXPLAIN ANALYZE 跑一遍查询获取执行计划，再把执行计划发给 AI，让它用人类语言解释"这个查询哪里慢、缺什么索引、应该怎么改写"。这相当于给每个 SQL 配备了一个免费的数据库性能顾问。

Schema 安全限制是值得称道的工程决策。系统表（pg_catalog、information_schema）被强制排除在查询范围外，防止用户不小心生成针对系统元数据的危险操作。同时支持 OpenAI 兼容 API（Ollama、LiteLLM、OpenRouter、vLLM），意味着用户完全可以本地部署模型，彻底告别 API 费用。

架构设计：模块化插件框架

代码采用清晰的分层架构，全部用 C++20 编写，充分利用现代 C++ 的结构化绑定和 std::format：

依赖管理使用 CMake + Git Submodule，third_party/ai-sdk-cpp 是 AI SDK 的 C++ 封装。代码质量不错：有 .clang-format 格式化配置、format-check CI 流程、完整的单元测试覆盖。

上手门槛：编译安装 vs. 包管理器

传统编译安装：需要 PostgreSQL 14+、CMake 3.16+、C++20 编译器。克隆仓库、初始化子模块、cmake 配置、make 编译、make install——五步走，适合有 Linux 服务器运维经验的开发者。

PIGSTY 一键安装：对于已经在用 PIGSTY 管理 PostgreSQL 的用户，只需要一条 pig install pg_ai_query，支持 PG 14 到 PG 18，覆盖 RPM（EL9/EL10）和 DEB（Debian 13、Ubuntu 24/26）平台，甚至有 aarch64 架构的预编译包。这是目前最推荐的方式。

Zeabur 云部署：懒得自己装？直接用 Zeabur 的预置模板，一键拉起带 pg_ai_query 的 PostgreSQL 容器，绑定 API Key 就能用。

局限与争议

AI 幻觉风险是首要问题。LLM 可能生成语法错误或语义错误的 SQL，特别是在 schema 描述不完整或表名/列名存在歧义时。项目有安全检查（系统表隔离、Schema 验证），但不能百分百保证 SQL 正确性。强烈建议用 explain_query() 二次验证。

API 费用不可忽视。每次查询都调用 LLM API，对于高频查询场景，OpenAI/Claude 的 API 费用会快速累积。本地模型（Ollama/vLLM）是出路，但需要额外的 GPU 资源。

调试困难。当 LLM 返回了奇怪的结果，排查链路很长——是 Prompt 约束不够？是 schema 描述不准确？还是 LLM 本身的理解有偏差？目前缺乏细粒度的调试日志。

不支持嵌套事务和 DDL。某些涉及多表复杂事务的操作，LLM 可能生成不安全的 SQL；DDL（CREATE/DROP/ALTER）操作虽然被 Prompt 允许，但实际效果需要充分测试。

行业意义：数据库工具的 AI 进化

pg_ai_query 代表了一个重要趋势：把 AI 能力下沉到数据库本身。传统工作流是"写代码 → 连数据库 → 查数据"，现在变成"描述需求 → 数据库自己生成 SQL → 执行"。这条路的方向是对的，但目前成熟度还不高，更适合作为辅助工具，而非生产环境的唯一查询入口。

它的价值在于：让 SQL 从"需要学习的技术"变成"可以自然对话的能力"，降低数据分析的门槛——这才是 AI 赋能数据库的真正意义。