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: 一个可选的用户名。如果包含，它应该在第二个斜杠 (/) 之后开始，并持续到冒号 (:)（如果也提供了密码）或直到 at 符号 (@)（如果没有提供密码）。password: 一个可选密码。如果包含，它在冒号 (:) 之后开始，并持续到 at 符号 (@)。
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在冒号和双斜杠 (://) 之后开始，并以 at 符号 (@) 结束。
要仅指定用户名，可以将其放在这两个符号之间
postgresql://username@
要指定用户名_和_密码，请先提供用户名，然后是冒号 (:)，再是密码和 at 符号
postgresql://username:password@
应用程序能够通过注意包含终止 at 符号 (@) 来将此数据解释为userspec。如果只提供一个字段（如果斜杠和 at 符号之间没有冒号），则将其解释为用户名。
指定服务器监听位置
在userspec之后是hostspec，它定义了服务器的监听位置。hostspec同样是可选的，但如果你不依赖客户端或库中设置的默认值，它几乎总是有用的。
hostspec由host和可选的port组成。host可以是本地可解析的主机名、由外部名称系统（如 DNS）解析的名称，或者 IP 地址或其他直接地址。端口表示 PostgreSQL 正在监听的端口号。
要指定应用程序应尝试连接到本地计算机上的默认 PostgreSQL 端口 (5432)，可以使用
postgresql://
如果需要包含用户名和密码，这些信息会首先出现，并用 at 符号分隔
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 将连接到给定数据库所需的所有信息编码在一个字符串中。由于这种灵活性和它们的广泛采用，理解如何解析和构建这些字符串会非常有帮助。