PostgreSQL 连接 URI 简介

介绍

连接到您的数据库服务器通常是您在设计和配置数据库支持的应用程序时需要完成的首批任务之一。虽然有许多方法可以为应用程序提供地址、监听端口、凭据和其他详细信息，但连接 URI（有时称为连接字符串或连接 URL）是最强大、最灵活的方式之一，可以在紧凑的格式中指定复杂的配置。

在本指南中，我们将讨论如何使用您的 PostgreSQL 数据库信息和 身份验证 详细信息格式化连接 URI。连接 URI 被分成几部分，因此我们将逐步介绍每个部分。

百分比编码值

在开始之前，我们应该提到 PostgreSQL 连接 URI 要求使用 百分比编码值。这意味着任何在 URL 中具有特殊含义的字符都必须转换为其百分比编码的对应字符，以确保库和应用程序能够正确解释它们。

您应该百分比编码的字符包括

• (空格)：%20
• %: %25
• &: %26
• /：%2F
• :：%3A
• =：%3D
• ?：%3F
• @: %40
• [：%5B
• ]：%5D

这些在连接 URI 中具有特殊含义。

因此，如果您的密码是...

pe@ce&lo\/3

...您需要在连接 URI 中将其指定为

pe%40ce%26lo\%2F3

如果您不确定是否应该对某个字符进行百分比编码，通常最好还是对其进行编码。例如，如果您不确定 \ 字符是否为保留字符，可以使用其百分比编码的等效字符 %5C 来确保安全

pe%40ce%26lo%5C%2F3

在构建连接 URI 时请牢记这一点。

快速概览

在详细介绍之前，我们可以查看 PostgreSQL 连接 URI 的规范

postgres[ql]://[username[:password]@][host[:port],]/database[?parameter_list]

\_____________/\____________________/\____________/\_______/\_______________/
     |                   |                  |          |            |
     |- schema           |- userspec        |          |            |- parameter list
                                            |          |
                                            |          |- database name
                                            |
                                            |- hostspec

方括号中的部分表示可选部分。您可能已经注意到 URI 的大部分部分都是可选的。您可能还注意到，您可以使用 URI 编码许多信息。

每个组件的简要说明

• postgres[ql]：模式标识符。可以是 postgresql 或简写为 postgres。
• userspec：URI 的可选组件，可用于指定要连接的用户和密码。
  • username：可选用户名。如果包含，它应从第二个斜杠 (/) 开始，一直持续到冒号 (:)（如果也提供了密码）或直到“@”符号 (@)（如果没有提供密码）。
  • password：可选密码。如果包含，它从冒号 (:) 开始，一直持续到“@”符号 (@)。
• hostspec：用于指定要连接到的主机名和端口的可选组件。
  • host：要连接到的服务器的可选 IP 地址、DNS 名称或本地可解析名称。主机一直持续到冒号 (:)（如果包含端口）或直到斜杠（如果没有包含端口）。
  • port：可选端口规范，用于指示 PostgreSQL 在服务器上监听的端口。端口从冒号 (:) 开始，一直持续到斜杠 (/)。
• database name：要连接到的单个数据库的名称。
• parameter list：可选的附加参数列表，可以影响连接行为。参数列表从问号 (?) 开始。
  • parameter pairs：参数列表由键值对组成。每个对中的键和值用等号 (=) 分隔，每个对用与号 (&) 与下一个对分隔。

以下是一个包含所有这些组件的 PostgreSQL 连接 URI 示例

postgresql://sally:[email protected]:5555/userdata?connect_timeout=10&sslmode=require&target_session_attrs=primary
    ^          ^         ^               ^           ^     ^          ^
    |- schema  |         |- password     |- host     |     |          |- parameter list
               |                                     |     |
               |- username                           |     |- database
                                                     |
                                                     |- port

指定 URI 类型

连接 URI 中的项目通常是协议规范或应用程序类型。由于 URI 将用于连接到 PostgreSQL 数据库并进行身份验证，因此我们需要使用一个标识符来向我们使用的应用程序和库表明这一点。

PostgreSQL 项目接受 postgresql:// 和 postgres:// 两种 URI 模式标识符作为有效标识符。因此，您应该用这两个字符串中的任何一个作为连接 URI 的开头。

postgresql://
postgres://

模式标识符将确保后续的信息在正确的上下文中被解释。

指定用户名和密码

URI 的下一部分是用户凭据。在规范中，这被称为 userspec。从技术上讲，userspec 是可选的，但如果您不想依赖应用程序或数据库配置的默认值，通常需要它。

如果包含 userspec，它将在冒号和双斜杠 (://) 后开始，并在 at 符号 (@) 处结束。

要只指定用户名，可以将其放在这两个符号之间。

postgresql://username@

要指定用户名和密码，请先提供用户名，然后紧跟一个冒号 (:)，然后是密码和 at 符号。

postgresql://username:password@

应用程序能够通过检测终止 at 符号 (@) 的包含来将此数据解释为 userspec。如果只提供了一个字段（如果在斜杠和 at 符号之间没有冒号），则将其解释为用户名。

指定服务器监听的位置

在 userspec 之后是 hostspec，它定义了服务器监听的位置。同样，hostspec 是可选的，但如果您不依赖客户端或库中设置的默认值，它几乎总是很有用的。

hostspec 由 host 和可选的 port 组成。host 可以是本地可解析的 hostname、由外部命名系统（如 DNS）解析的名称、IP 地址或其他直接地址。端口表示 PostgreSQL 监听的端口号。

要指定应用程序应尝试连接到本地计算机上的默认 PostgreSQL 端口 (5432)，可以使用：

postgresql://127.0.0.1

如果您需要包含用户名和密码，这些信息将首先出现，并用 at 符号隔开。

postgresql://username:password@localhost

要指定在非标准端口上运行的远程服务器，请使用冒号将这些详细信息隔开。例如，要连接到 198.51.100.22 上的端口 3333，可以使用：

postgresql://username:[email protected]:3333

您实际上可以提供多个主机和端口对，并用逗号 (,) 隔开，以告知应用程序在第一个无法到达时尝试连接后来的服务器。例如，要扩展前面的示例以包含在 198.51.100.33 上端口 5555 上监听的备用服务器，可以使用：

postgresql://username:[email protected]:3333,198.51.100.33:5555

符合标准的客户端和应用程序将首先尝试连接到监听 198.51.100.22:3333 的服务器。如果失败，它们将尝试连接到监听 198.51.100.33:5555 的 PostgreSQL 数据库。

提供数据库名称

在 hostspec 之后，下一部分数据是数据库名称。虽然这对于所有数据库管理系统来说并不适用，但在 PostgreSQL 中，您必须在建立连接时连接到一个特定的数据库。

数据库名称以斜杠 (/) 开头，一直延续到行尾或问号 (?) 处。如果您不依赖默认值，则必须包含数据库名称。

要连接到名为 sales 的数据库，该数据库托管在监听 198.51.100.22:3333 的 PostgreSQL 服务器上，可以键入：

postgresql://username:[email protected]:3333/sales

指定其他参数

连接 URI 的最后一部分用于为连接提供其他参数。参数列表以一个引导问号 (?) 开头，一直延续到行尾。

列出的每个参数都定义为用等号 (=) 连接的键值对。在第一个参数对之后，每个额外的键值对都用一个与号 (&) 隔开。

例如，要指定客户端应该对之前定义的连接应用 10 秒的超时时间，可以使用：

postgresql://username:[email protected]:3333/sales?connect_timeout=10

如果您想提供其他参数，可以在每个对之间添加一个与号 (&)。例如，我们可以另外指定需要 SSL 并且只想在服务器是复制集中的主服务器时连接，可以另外添加：

postgresql://username:[email protected]:3333/sales?connect_timeout=10&sslmode=require&target_session_attrs=primary

PostgreSQL 文档有 参数的完整列表，您可以阅读这些文档以了解更多信息。

结论

在本指南中，我们讨论了什么是 PostgreSQL 连接 URI，如何解释各个组件以及如何在给定一组连接信息的情况下构建自己的 URI。连接 URI 在单个字符串中编码连接到特定数据库所需的所有信息。由于这种灵活性以及它们被广泛采用，了解如何解析和构建这些字符串非常有用。