你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
本文介绍 PostgreSQL 扩展中用于Visual Studio Code的高级连接功能。 当需要重复使用现有连接字符串、提供证书文件以进行更严格的 TLS 验证或通过堡垒主机与 SSH 隧道进行连接时，请使用这些选项。
Tip
有关标准身份验证、SSL 模式选择、服务器组和保存的连接，请参阅 连接和标识。
使用连接字符串输入模式
在连接对话框中选择“ 连接字符串 ”选项卡（在 “连接方式：”下）粘贴现有连接定义。 该扩展会自动分析字符串并填充连接字段。
页面使用双列布局：
- 左列：一个标记为 连接字符串 的文本区域，可在其中粘贴字符串。 文本区域下方的提示写着请勿在连接字符串中包含密码。
- 右侧列：一个只读的 连接详细信息 面板，会在提取过程中显示已解析出的 服务器名称、用户名 和 数据库名称 值。
在您输入或粘贴时，系统会实时解析。 如果分析程序检测到缺少的服务器或用户值，则会在文本区域上方显示验证错误。
支持的格式
该扩展可识别九种连接字符串格式：
| Format | 前缀或触发词 | 示例 |
|---|---|---|
| PostgreSQL URI |
postgres:// 或 postgresql:// |
postgresql://user:password@host:5432/dbname?sslmode=require |
| JDBC | jdbc:postgresql:// |
jdbc:postgresql://host:5432/dbname |
| 以分号分隔（key=value） | 包含 ; |
host=localhost;port=5432;dbname=mydb;user=postgres;password=secret |
psql 命令行 |
psql |
psql -h host -p 5432 -U user -d dbname |
| 环境变量导出 | export |
export PGHOST=localhost后跟PGPORT、PGUSER、PGDATABASE、PGPASSWORD |
| Node.js | new Client |
new Client({ host: "localhost", port: 5432, user: "postgres", database: "mydb" }) |
| Python （psycopg2） | psycopg2.connect |
psycopg2.connect(user="postgres", password="<your-password>", host="localhost", port=5432, database="mydb") |
| PHP | pg_connect |
pg_connect("host=localhost port=5432 dbname=mydb user=postgres") |
| Ruby | PG::Connection.new |
PG::Connection.new(host: "localhost", port: "5432", user: "postgres", database: "mydb") |
分析程序从所有格式中提取 主机、 用户、 端口、 数据库和 密码 。 如果对话框中已填充密码字段，分析器将保留现有值。
Note
解析后，您仍然可以打开 高级 抽屉面板来配置连接字符串未包含的设置，例如 SSH 隧道或每个连接的 AI 访问模式（在 Visual Studio Code 中为 Copilot 访问模式，在 Cursor 中为 AI 访问模式）。
配置证书文件
当您的环境需要双向 TLS 或显式证书颁发机构验证时，请使用 高级连接设置 抽屉面板中 SSL 折叠部分里的证书文件设置。
SSL 根证书模式
SSL 根证书模式下拉列表控制扩展如何提供根 CA 证书。 选择下列值之一：
| Mode | Behavior |
|---|---|
| 没有 | 不使用根证书。 该扩展不会验证服务器证书链。 |
| System | 该扩展使用您的操作系统的受信任的证书存储区。 此模式需要 验证完全 SSL 模式;扩展会自动强制实施此操作。 |
| 自定义文件 | 将显示一个标有 SSL 根证书文件名 的文本字段。 输入 PEM 编码的根 CA 证书文件的路径。 |
Important
选择 “系统”时，SSL 模式将自动设置为 “验证完全 ”。 如果在 系统 处于活动状态时将 SSL 模式更改为另一个值，则会显示验证错误：“使用系统证书存储时需要Verify-Full SSL 模式。
客户端证书字段
通过在 SSL 部分的这些字段中提供路径来配置双向 TLS：
| 字段标签 | 财产 | 说明 |
|---|---|---|
| SSL 证书文件名 | sslcert |
客户端证书文件的路径。 |
| SSL 密钥文件名 | sslkey |
客户端私钥文件的路径。 |
| SSL 根证书文件名 | sslrootcert |
根 CA 证书的路径（仅在 SSL 根证书模式 为 自定义文件时可见）。 |
| SSL CRL 文件名 | sslcrl |
证书吊销列表文件的路径。 |
| 使用 SSL 压缩 | sslcompression |
在 SSL 连接上启用压缩。 |
Tip
对于 Verify-CA 和 Verify-Full 模式，请始终配置根证书，以便扩展可以验证服务器证书。 使用 系统 模式依赖于操作系统的受信任 CA 存储，而无需指定文件路径。
通过 SSH 隧道进行连接
SSH 隧道通过加密的 SSH 通道传输 PostgreSQL 连接。 当无法从工作站直接访问数据库时，请使用此方法。 例如，当服务器驻留在堡垒主机后面的专用网络中时。
启用隧道
- 打开连接对话框，然后选择“高级”，打开“高级连接设置”侧边栏。
- 展开 SSH 隧道 折叠面板。
- 勾选“启用 SSH 隧道”开关。 将显示 SSH 连接字段。
SSH 隧道字段
| 字段标签 | 说明 |
|---|---|
| 主机 | SSH 服务器的主机名或 IP 地址（堡垒主机）。 |
| 港口 | SSH 服务器端口号 （默认值： 22） 。 |
| username | 使用 SSH 服务器进行身份验证的用户名。 |
| Authentication | SSH 身份验证方法。 选择 “密码”、“ 标识文件”或 “SSH 代理”。 |
其余字段根据所选的身份验证方法更改：
| 身份验证方法 | 显示的其他字段 |
|---|---|
| 密码 | password/passphrase：输入 SSH 密码。 保存密码/通行短语 复选框以保存凭据。 |
| 标识文件 |
标识文件：输入 SSH 私钥的完整路径（例如 ~/.ssh/id_ed25519）。
password/passphrase：如果私钥已加密，请输入密钥通行短语。
保存密码/通行短语 复选框。 |
| SSH 代理 | 无其他字段。 该扩展将身份验证委托给系统的 SSH 代理（ssh-agent在 macOS 和 Linux 上，Windows上的 OpenSSH 身份验证代理服务）。 |
隧道的工作原理
启用 SSH 隧道后，扩展首先建立 SSH 连接，创建本地端口转发，然后通过该转发连接到 PostgreSQL。 因此：
- 主连接字段中 的服务器名称 应是 SSH 主机（通常是
localhost或专用 IP）中显示的数据库地址。 -
端口应是目标主机上的 PostgreSQL 端口（通常
5432）。 - SSH 隧道建立增加了连接延迟。 如果出现超时，请考虑在高级选项中增加 Connect 超时 值。
选择正确的高级选项
| Scenario | 建议的功能 |
|---|---|
你有现有的 PostgreSQL URI、应用代码段或 psql 命令 |
选择“ 连接字符串 ”选项卡以自动填充字段。 |
| 您的组织需要自定义 CA 文件或双向 TLS | 在高级设置抽屉的 SSL 部分中配置 SSL 证书字段。 |
| 您需要使用操作系统证书存储来验证服务器 | 将 SSL 根证书模式 设置为 “系统 ”，将 SSL 模式 设置为 “验证完整”。 |
| 数据库仅可通过跳板机或堡垒主机访问 | 在高级抽屉的 SSH 隧道 部分中启用 SSH 隧道。 |