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:sallyspassword@dbserver.example: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 在冒号和双斜杠 (://) 后开始，并以 @ 符号 (@) 结尾。

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

postgresql://username@

要指定用户名和密码，请先提供用户名，然后是冒号 (:)，接着是密码和 @ 符号

postgresql://username:password@

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

指定服务器监听位置

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

hostspec 由一个 host 和一个可选的 port 组成。host 可以是本地可解析的主机名、由DNS等外部命名系统解析的名称，也可以是IP地址或其他直接地址。端口表示PostgreSQL正在监听的端口号。

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

postgresql://localhost

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

postgresql://username:password@localhost

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

postgresql://username:password@198.51.100.22:3333

您实际上可以提供多个主机和端口对，用逗号 (,) 分隔，以告诉应用程序如果第一个服务器无法访问，则尝试后面的服务器。例如，要将上一个示例扩展为包含一个在 198.51.100.33 上监听 5555 端口的备用服务器，您可以使用

postgresql://username:password@198.51.100.22:3333,198.51.100.33:5555

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

提供数据库名称

在 hostspec 之后，下一部分数据是数据库名称。虽然并非所有数据库管理系统都如此，但在 PostgreSQL 中，建立连接时必须连接到特定的数据库。

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

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

postgresql://username:password@198.51.100.22:3333/sales

指定额外参数

连接 URI 的最后一部分用于为连接提供额外参数。参数列表以开头的问号 (?) 引入，并持续到行尾。

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

例如，要指定客户端应为我们之前定义的连接应用 10 秒超时，您可以使用

postgresql://username:password@198.51.100.22:3333/sales?connect_timeout=10

如果您想提供额外参数，您可以在每个参数对之间用和号 (&) 添加。例如，我们可以额外指定我们需要 SSL，并且只在服务器是副本集中的主服务器时才连接，我们可以额外添加

postgresql://username:password@198.51.100.22:3333/sales?connect_timeout=10&sslmode=require&target_session_attrs=primary

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

总结

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