Connection refused 真相是数据库未监听请求，而非插件问题；90% 情况为服务未启动、bind-address 仅限 127.0.0.1、防火墙拦截或 Docker host 配置错误，需先验证 mysqladmin ping、docker ps 或 systemctl 状态。
Connection refused 真相：不是插件连不上，是数据库根本没接收到请求
VSCode 本身不运行数据库服务，“Connection refused”90% 意味着目标数据库进程未启动、端口未监听，或网络层被阻断。插件冲突不会导致这个错误——它只会让连接配置不生效、测试按钮点不动、或者日志里压根没发请求。
先做三件事：
- 本地 MySQL：运行
mysqladmin ping -u root -p，输入密码后看到mysqld is alive才算活 - 本地 PostgreSQL：运行
pg_ctl status或sudo systemctl is-active postgresql - Docker 容器：执行
docker ps | grep postgres或docker ps | grep mysql，确认 STATUS 是Up而非Exited
如果这些都通不过，别碰 VSCode 插件设置，先解决数据库服务本身。
SQLTools 驱动未激活：插件装了但等于没装
vscode-sqltools 是个壳，真正干活的是独立安装的驱动插件（如 SQLTools PostgreSQL Driver）。只装主插件不装驱动，连接时会静默失败，或报 MissingModuleError: pg、Cannot find module 'mssql' 这类错误。
检查和修复步骤：
- 打开命令面板（
Ctrl+Shift+P），输入Extensions: Show Installed Extensions，确认驱动插件已启用（比如bradymholt.pgsql或mtxr.sqltools-mssql-driver） - 驱动插件名必须含
driver或明确标注数据库类型；SQLTools主体插件 ID 是mtxr.sqltools，二者缺一不可 - 重启 VSCode —— 驱动插件不会热加载，不重启就无法注册到 SQLTools 的连接工厂
- 若仍报模块缺失，手动检查路径：
~/.vscode/extensions/mtxr.sqltools-*/packages/driver.pg/下是否存在package.json和dist/
多个数据库插件共存时的端口劫持与命令抢占
当同时启用 vscode-sqltools、Database Client（bradymholt.pgsql）、PostgreSQL（ms-vscode.vscode-postgresql）等插件时，它们可能注册同名命令（如 postgres.connect）或监听同一端口事件，导致连接面板打不开、右键菜单消失、甚至 Extension host terminated unexpectedly 崩溃。
快速定位方法：
- 终端运行
code --disable-extensions启动干净环境，再试连接 —— 若成功，100% 是插件冲突 - 打开开发者工具（
Ctrl+Shift+I），切到 Console 标签页，搜索Command '或Conflict detected，直接定位冲突命令来源 - 运行
Developer: Show Running Extensions，观察是否有插件状态为Activation failed或加载耗时 >1000ms（常见于旧版ms-python.python干扰 SQLTools 初始化） - 禁用全部插件后，按“数据库类型”分批启用：先只留
SQLTools + 对应驱动，验证通过后再加其他，避免混用同类插件
密码含特殊字符却未 URL 编码：连对了库，输错了密码
VSCode 插件底层大多用标准 URL 格式解析连接参数（如 postgresql://user:pass@word@localhost:5432/db）。其中 @、/、:、? 都是保留字符，未编码会导致解析截断 —— 看似填了完整密码，实际只传了 pass，后面全被当成 host 或 port。
正确做法：
- 把密码中所有特殊字符转义：
@→%40，/→%2F，:→%3A，?→%3F - 不要依赖插件 UI 的“密码字段”自动处理 —— 多数插件（包括 SQLTools）在连接串模式下完全不处理编码，只原样拼接
- 测试方式：用
psql或mysql命令行复现，例如psql "postgresql://user:pass%40word@localhost:5432/db"，能连上才说明编码正确 - 如果用的是 Windows，注意反斜杠
在 JSON 配置里需双写：\
最常被忽略的其实是 Docker 场景下的 host：本地容器连接填 localhost 必然失败，得用 host.docker.internal（macOS/Windows）或宿主机真实 IP（Linux），这个错配比密码编码问题更隐蔽，也更难排查。
