连接和身份

适用于Visual Studio Code的 PostgreSQL 扩展提供了一个连接对话框，支持多种身份验证方法、SSL/TLS 加密和组织工具，例如服务器组和已保存的连接。 本文介绍核心连接任务：打开对话框、选择身份验证方法、保存和重用连接以及组织服务器。

打开连接对话框

可以通过多种方式打开连接对话框：

• 连接：将鼠标悬停在 “连接” 部分标头上，然后选择“ 添加新连接 ”（ + 图标）。
• 命令面板：运行 PGSQL：添加新连接。
• 已保存或最近连接：从侧面板中的 “已保存连接 ”或“ 最近连接” 列表中选择连接卡，将其设置加载到对话框中。

打开新对话框时，标头将读取 “新建连接 ”，标题将读取 “连接到 PostgreSQL 服务器”。 编辑现有连接时，标头将更改为 “编辑连接”。

选择输入模式

对话框顶部的 通过以下方式连接： 选项卡可让您选择如何提供连接信息：

这三种模式共享对话框底部的相同“保存和测试连接”按钮。 高级按钮可在任何模式下打开高级连接设置抽屉。

填写连接参数

使用“ 参数 ”选项卡时，对话框将显示以下主字段：

根据身份验证类型显示其他字段。 对于 Entra 身份验证，对话框显示 Entra 帐户、 Entra 用户名和 租户。 对于 AWS IAM（RDS/极光），对话框显示 AWS 配置文件 和 AWS 区域。

身份验证类型

身份验证类型下拉列表提供四个选项。

密码

密码 身份验证是标准的 PostgreSQL 方法。 您提供用户名和密码，服务器会根据其身份验证配置（通常为 pg_hba.conf）对其进行验证。

1. 将 身份验证类型 设置为 密码。
2. 输入用户名和密码。
3. （可选）选择“ 保存密码 ”以安全地存储密码。
4. 选择“ 保存并连接”。

密码存储

选择“保存密码”时，扩展会通过Visual Studio Code SecretStorage API 存储密码，该 API 委托给操作系统的凭据管理器：

• macOS：密钥链
• Windows：凭据管理器
• Linux： libsecret （GNOME Keyring 或 KWallet）

保存的密码与特定连接相关联，永远不会存储在纯文本设置文件中。

Microsoft Entra 身份验证

Microsoft Entra身份验证（以前Azure Active Directory）为Azure Database for PostgreSQL灵活服务器提供基于令牌的无密码身份验证。 对话框标记此选项 Entra Auth。

若要使用 Entra 身份验证进行连接，请执行以下操作：

1. 添加 Entra 帐户。 打开命令面板并运行 PGSQL：添加Microsoft Entra帐户。 在打开的浏览器窗口中，使用 Entra 凭据登录。
2. 打开连接对话框。 将 身份验证类型 设置为 Entra Auth。
3. 选择你的帐户。 从 Entra 帐户 下拉列表中选择添加的帐户。
4. 选择租户。 如果帐户属于多个租户，请从 “租户 ”下拉列表中选择相应的租户。
5. 输入 Entra 用户名。 输入映射到你的标识的 PostgreSQL 角色对应的 Entra 用户名。
6. 连接。 选择“ 保存并连接”。 该扩展会获取访问令牌，并代表你向 PostgreSQL 服务器进行身份验证。

保存的 Entra 连接配置文件继续使用旧 AzureMFA 值。 bearer-token:entra-id规范值是为服务器驱动的调度和将来的配置文件迁移保留的。

若要删除 Entra 帐户，请运行 PGSQL：从命令面板中删除Microsoft Entra帐户，然后选择要删除的帐户。 若要清除缓存的令牌而不删除帐户，请运行 PGSQL：清除Microsoft Entra帐户令牌缓存。

双帐户模型

该扩展支持用于Azure方案的双帐户模型。 可以使用一个 Entra 帐户进行身份验证，另一个帐户用于浏览Azure资源（订阅、资源组和服务器）。

• 连接对话框中的 Entra Account 字段决定使用哪个标识向数据库进行身份验证。
• “浏览Azure”选项卡使用登录Visual Studio Code的Azure帐户（通过Azure资源扩展）进行订阅和资源枚举。

AWS IAM （RDS/极光）

AWS IAM 身份验证使用 AWS 签名的数据库身份验证令牌，而不是存储的密码。 仅对启用了 IAM 数据库身份验证的 Amazon RDS for PostgreSQL 或 Amazon Aurora PostgreSQL 数据库终结点使用此选项。 手动输入的 AWS 区域 可以补充区域推理，但它不会使自定义 PostgreSQL 主机、非 RDS 主机或 CNAME 别名受支持。 对话框标记此选项 AWS IAM （RDS/Aurora）。

若要使用 AWS IAM 身份验证进行连接，请执行以下操作：

1. 准备 AWS 凭据。 配置组织所需的 AWS CLI 流。 示例包括 aws configure、aws sso login --profile <profile> 或特定于组织的 credential_process 设置。
2. 打开连接对话框。 将身份验证类型设置为 AWS IAM （RDS/Aurora）。
3. 输入服务器端点。 在 服务器名称中使用 Amazon RDS 或 Aurora PostgreSQL 端点。
4. 输入数据库角色名称。 在 “用户名”中，输入 PostgreSQL 数据库用户或角色。 这不是 AWS 配置文件、IAM 用户、IAM 角色或 ARN。
5. 选择 AWS 凭据源。 选择或输入 AWS 配置文件。 将 AWS 配置文件 留空以使用默认 AWS 凭据链。
6. 根据需要设置 AWS 区域。 该扩展会在可能的情况下根据标准的 RDS 和 Aurora 主机名推断区域信息。 如果主机名不包含该区域，请在 AWS 区域中输入它。
7. 连接。 选择“ 保存并连接”。 该扩展对短生存期身份验证令牌进行签名，并将其用作新连接的 PostgreSQL 密码。

AWS 凭据链支持环境变量、共享 AWS 配置和凭据文件、AWS SSO 配置文件和 credential_process 配置文件。 它不使用 EC2 或 ECS 实例/容器元数据凭证，也不使用基于元数据的 credential_source 配置链。

AWS IAM 数据库身份验证令牌有效期为 15 分钟。 扩展会根据需要获取新令牌，而基础 AWS 凭据仍然有效。 无需手动令牌刷新步骤。

None

无 完全跳过身份验证。 该扩展无需发送凭据即可连接。 此选项适用于配置了 trust 身份验证的 PostgreSQL 服务器或类似的无凭据配置。

连接、测试和断开连接

填写连接详细信息后，请使用连接对话框中的操作和 “连接” 树保存配置文件、连接、编辑或删除服务器。

保存和连接

填写连接详细信息后，选择“ 保存并连接” 以建立连接。 此按钮执行两个操作：

1. 将此连接作为配置保存在 VS Code 设置中。
2. 连接到服务器。

如果连接成功，服务器会显示在 “连接” 树中。 连接也会显示在连接对话框中的 “已保存连接 ”和“ 最近连接” 列表中。

测试连接

选择 “测试连接 ”以验证连接参数，而无需保存配置文件或将服务器添加到 连接 树。 该按钮在测试运行时显示加载动画，成功时显示对勾图标，失败时显示警告图标。

断开连接

若要从服务器断开连接，请执行以下操作：

• 连接：右键单击服务器节点并选择“ 断开连接”。
• 命令面板：运行 PGSQL：断开连接。

编辑现有连接

若要编辑保存的连接，请在 “连接” 树中右键单击服务器，然后选择“ 编辑连接”。 连接对话框将以编辑模式打开，标题为 编辑连接，并以当前配置文件名称为标题。 进行更改，然后选择“ 保存并连接 ”以重新连接更新的设置。

高级连接设置

单击主要字段下方的“高级”按钮，以打开“高级连接设置”抽屉面板。 抽屉包含：

• 顶级选项： 范围 （用户或工作区）、 端口、 应用程序名称、 连接超时和 多子网故障转移。
• 分组区段：用于 源、安全、服务器、客户端、SSL、Copilot 和 SSH 隧道的可折叠手风琴区段。

Scope 选项控制连接配置文件的保存位置：

有关 SSL 和 SSH 隧道配置详细信息，请参阅 高级连接选项。

按连接的 Copilot 访问模式

高级抽屉中的Copilot部分包含一个Copilot 访问模式下拉列表，提供三个选项：

SSL 和 TLS

SSL/TLS 对 Visual Studio Code 与 PostgreSQL 服务器之间的连接进行加密。 在高级连接设置抽屉面板的 SSL 部分中，或在连接字符串中配置 SSL 模式。

SSL 模式

管理已保存的连接和最近使用的连接

连接对话框包括一个侧面板，其中包含两个列表：

• 已保存的连接：以前使用 保存和连接保存的连接。 每张卡片都显示服务器的显示名称。 将鼠标悬停在卡片上以显示删除按钮。 选择一张卡片，将其设置加载到对话框中。
• 最近的连接：您最近使用过的连接，无论您是否使用连接名称保存过这些连接。 将鼠标悬停以显示删除按钮。

“ 最近连接” 列表受 pgsql.maxRecentConnections 设置限制。 每个配置文件和数据库同时打开的最大连接数由 pgsql.maxConnections 设置控制（默认值：10）。

服务器组

服务器组有助于在 “连接” 树中组织连接。 可以为每个组分配自定义名称和颜色，以便更轻松地识别开发、过渡和生产等环境。

创建服务器组

1. 右键单击 “连接 ”树，然后选择“ 创建服务器组”。
2. 在对话框中，输入 名称、可选 说明，然后选择组 的颜色 。

编辑或删除服务器组

• 编辑：右键单击 “连接 ”树中的服务器组，然后选择 “编辑服务器组 ”以更改其名称、说明或颜色。
• 删除：右键单击服务器组并选择“ 删除”。 组中的连接不会被删除;它们移动到默认组。

为组分配连接

创建或编辑连接时，连接对话框在主字段区域中包括 服务器组 下拉列表。 从列表中选择一个组，将连接分配给该组。

组颜色在 连接 树中显示为组名称旁边的彩色条，便于快速识别。

Azure元数据

连接到 Azure Database for PostgreSQL 灵活服务器时，连接对话框可在表单旁显示 Azure 元数据 面板。 选择“提取Azure元数据”后，此面板会显示服务器的订阅和资源组。 包含 Azure 元数据即可启用管理功能，例如 服务器仪表板 和 Azure Monitor 指标。

排查常见连接问题

连接尝试失败时，原因通常是网络、身份验证或 SSL 设置。 以下部分介绍最常见的情况。

连接被拒绝或超时

如果在身份验证开始前连接失败，请先验证服务器名称和端口。 请确保 PostgreSQL 正在运行，可从计算机访问端口，并且任何网络防火墙规则都允许连接。 您可以在高级连接设置抽屉面板中调整连接超时，以便为较慢的网络连接留出更多时间。

SSL 或证书验证错误

如果服务器需要加密，请确认高级抽屉的 SSL 节中的所选 SSL 模式是否与服务器配置匹配。 对于 Verify-CA 和 Verify-Full，请确保配置了正确的 CA 证书。 有关证书文件的详细信息，请参阅 高级连接选项。

Microsoft Entra登录或令牌问题

如果 Entra 身份验证失败，请确认目标Azure Database for PostgreSQL灵活服务器已启用 Entra 身份验证，然后验证是否在连接对话框中选择了正确的帐户和租户。 如果需要，请运行 PGSQL：删除Microsoft Entra帐户并重新添加帐户。 若要重置缓存的令牌，请运行 PGSQL：清除Microsoft Entra帐户令牌缓存。

AWS IAM 配置文件或令牌相关问题

如果 AWS IAM 身份验证失败，请验证 服务器名称 是否为 Amazon RDS 或 Aurora PostgreSQL 终结点，而不是自定义主机名或 CNAME 别名。 确认 用户名 是 PostgreSQL 数据库角色，并且该角色已在服务器上启用 IAM 数据库身份验证。 验证所选 AWS 配置文件 是否可以获取支持的 AWS 凭据;例如，为命名配置文件运行 aws sts get-caller-identity --profile <profile> ，或者在使用默认凭据链时省略 --profile 。 如果受支持终结点的区域推理失败，请手动输入 AWS 区域 。

连接字符串解析未填充正确的字段

如果粘贴连接字符串未填充预期值，请查看高级连接选项中支持的输入模式。 如果源格式异常，请切换到“ 参数 ”选项卡并手动输入值。

相关内容

• 高级连接选项
• 快速入门：连接和查询 PostgreSQL
• Azure服务器管理
• 创建 PostgreSQL 服务器