sqltools + sqltools postgresql driver 是唯一稳定组合：必须同时安装二者并手动 connect，host 用 127.0.0.1、database 必填、password 含特殊字符须用表单模式，执行用 ctrl+alt+r，导出 csv 前需设 sqltools.resultslimit=0 并确认右下角绿色图标与右上角连接已选中。

SQLTools + PostgreSQL Driver 是唯一能稳定连上的组合

VSCode 原生不支持任何数据库协议，所谓“连接 PostgreSQL”，本质是装对两个扩展并手动激活连接。只装 SQLTools 主体插件，一定会卡在 Driver not found: postgresql；必须额外安装 SQLTools PostgreSQL Driver（作者 mtxr，搜 @tag:sqltools-driver 可筛选）。PostgreSQL by Chris Kolkman 这类依赖本地 psql 的插件，在 M1/M2 Mac 上常报 Command 'psql' not found 或 Protocol error: unrecognized message type，且不支持 resultsLimit=0 和 sslmode=verify-full，连 Supabase、RDS 会直接超时。

host/database/password 这三项填错，90% 连不上

即使驱动装对了，以下字段填错仍导致静默失败或超时：

• host 写 localhost：macOS/Linux 下易触发 IPv6 解析失败，统一改用 127.0.0.1；Windows 可用 localhost，但混用环境建议也写死 127.0.0.1
• database 为空：PostgreSQL 不允许空库名，哪怕只想查有哪些库，也得填一个真实存在的库（如 postgres 或 myapp_dev）
• password 含 @、/ 等特殊字符：URL 格式解析会崩，务必用表单模式填写，别手写 postgresql://user:pass@host/db
• 端口默认是 5432，但 Docker 容器若映射到其他端口（如 5433），必须显式填对，否则报 Connection refused

执行 SQL 前必须手动 Connect，不是配完就自动连

配置好连接后，VSCode 不会自动尝试连接，也不会记住上次状态。常见错误 No active connection found 几乎全是这个原因：

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 右键侧边栏 SQLTools 连接项 → Connect，看到右下角状态栏出现绿色图标和连接名（如 postgres@127.0.0.1）才算成功
• 新建 .sql 文件后，右上角数据库下拉框必须选中已连上的那个连接，否则执行无效
• 快捷键是 Ctrl+Alt+R（Windows/Linux）或 Cmd+Alt+R（macOS），不是 Ctrl+Enter；后者在某些旧配置里可能绑定失败
• 光标必须落在完整语句内（不能跨行选中，也不能停在注释或空行），否则只执行光标所在行

导出 CSV 前先看字段类型，不然 timestamp/jsonb 会失真

点「导出为 CSV」看着方便，但实际容易丢信息：

• timestamp with time zone 字段会被转成本地时区字符串，原始时区信息丢失
• jsonb 字段可能被扁平化、截断，甚至因换行符导致 CSV 列错位
• 导出前先执行 SELECT 查看实际返回结构；想导全量数据？进 VSCode 设置搜 sqltools.resultsLimit，设为 0（默认只拉前 100 行）

最常被忽略的是连接状态的双重确认：右下角绿色图标 + 右上角下拉框选中，缺一不可。很多问题不是配置错，而是以为连上了，其实只是配置存了没点 Connect。