SQLTools + SQLTools PostgreSQL Driver 是VSCode中唯一不依赖本地psql、自带JS协议实现、支持完整SSL和全量导出的稳定PostgreSQL连接方案。
别装“PostgreSQL by Chris Kolkman”——它依赖本地 psql，没装或版本不匹配就卡在 Command 'psql' not found 或报 Protocol error: unrecognized message type；真要稳定连 PostgreSQL，必须用 SQLTools + SQLTools PostgreSQL Driver 这套组合。
为什么 SQLTools 是唯一靠谱选择
VSCode 本身不带数据库协议实现，所有连接能力都靠扩展补全。很多用户搜“PostgreSQL”随手装第一个，结果发现：PostgreSQL by Chris Kolkman 实际是包装本地 psql 命令行的外壳，一旦系统没装 psql（比如 macOS 上只用 Homebrew 装了 postgresql@15 但没 link）、或版本太老（psql v12 连不了 v16 服务端），就会静默失败；而 SQLTools 自带纯 JS 实现的 PostgreSQL 协议驱动，不依赖外部命令，SSL 支持完整（require / verify-full 都能配），还能设 resultsLimit=0 导出全量数据。
常见踩坑点：
- 只装了
SQLTools核心，没装SQLTools PostgreSQL Driver→ 点连接直接报Protocol error: unrecognized message type - 同时装了
PostgreSQL by Chris Kolkman和SQLTools→ 扩展冲突，右下角状态栏图标反复闪烁，连接时序错乱 - 用旧版
SQLTools（v0.x）→ 不支持sslmode=verify-full，连 Supabase 或 AWS RDS 会超时
连接失败时优先检查这三处
报 Connection refused 或 FATAL: password authentication failed，90% 不是密码错，而是底层链路断了：
-
pg_isready -h 127.0.0.1 -p 5432返回不是accepting connections→ PostgreSQL 服务根本没跑（Docker 容器停了、brew services stop postgresql后没重开） -
host填了localhost→ macOS/Linux 下默认走 Unix socket，但SQLTools强制走 TCP，必须填127.0.0.1；Windows 可混用，但为统一建议全用127.0.0.1 -
pg_hba.conf没加规则 → 本地 TCP 连接至少要有host all all 127.0.0.1/32 md5，改完执行pg_ctl reload或重启服务
执行 SQL 前必须确认的两个状态
连上不等于能执行。VSCode 里执行查询是上下文敏感操作，漏一步就报 No active connection found：
- 右下角状态栏必须显示绿色数据库图标 + 当前连接名（如
postgres@127.0.0.1），点击可切换；如果只看到灰色图标，说明连接未激活 - 打开
.sql文件后，右上角必须出现数据库下拉框且已选中目标连接；这个下拉框决定语句发给谁，和文件路径、文件名完全无关 - 执行前必须选中整段 SQL（或光标落在语句内），再按快捷键：
Ctrl+Alt+R（Windows/Linux）或Cmd+Alt+R（macOS）；按Ctrl+Enter是部分插件的旧绑定，SQLTools默认不认
导出 CSV/JSON 时容易被忽略的细节
结果表格出来后，导出按钮不是一直可用：
- 光标必须点进任意一个单元格，右上角的向下箭头+表格图标才会高亮；点「磁盘」图标只会保存
.sql文件 - 默认只查前 100 行，想导全部？进 VSCode 设置搜
sqltools.resultsLimit，改成0（不是留空，也不是填-1） - 密码含
@、/、:等字符？连接配置里不用 URL 编码——SQLTools内部自动处理；但如果你手写连接串（比如在connections.json里），就得手动encodeURIComponent()
最常被跳过的动作是：连上之后没右键连接项点 Connect，就急着写 SQL。状态栏图标不绿，一切执行都是空转。另外，connections.json 文件位置在 ~/.sqltools/connections.json，改完不用重启 VSCode，但必须重新触发一次连接动作才生效。
