HOWTO · Postgres
Postgres 连接字符串
本文展示了 Postgres 中连接字符串的正确格式。
本页内容
PostgreSQL 客户端使用连接字符串定位数据库,并提供身份验证所需的信息。格式正确的 URI 可以连接到本地服务器或远程主机;服务器也必须可访问,并允许指定用户连接。
PostgreSQL 连接字符串格式
PostgreSQL URI 的格式如下:postgresql://[user[:password]@][host][:port][/dbname][?param=value&…]。协议方案也可以写作 postgres://。用户名和密码用于标识数据库角色,主机名指定服务器,端口指定服务器监听的端点,路径则指定数据库。查询参数可添加连接设置,例如 sslmode。
对于本地连接,libpq 客户端会将省略的主机名视为本地套接字;如果使用 TCP 连接,常见的主机名是 localhost。TCP 默认端口为 5432。如果服务器或客户端经过不同配置,这些默认值也可能不同。数据库名不一定与用户名相同,而且该角色必须有权连接相应数据库。
构建并使用连接字符串
建立本地 TCP 连接时,请将各项替换为服务器上配置的值:postgresql://app_user:your_password@localhost:5432/inventory。连接远程数据库时,将 localhost 替换为管理员或服务提供商提供的主机名。请使用分配给你的端口、数据库和角色,不要假设本地默认值也适用。
URI 语法会将 @、/ 和 : 等字符视为分隔符,因此,插入凭据前,必须对凭据中包含的这些字符进行百分号编码。请分别构建并编码 URI 的各个组成部分,不要直接拼接未经处理的凭据。
运行以下示例,查看 URI 如何对凭据中的保留字符进行编码。代码和示例输出中的标签及内容保持英文原样:
本节中的代码以及显示的标签或输出仍为英文。
from urllib.parse import quote
user = quote("app_user", safe="")
password = quote("my@pass/word", safe="")
host = "localhost"
port = "5432"
database = quote("inventory", safe="")
uri = f"postgresql://{user}:{password}@{host}:{port}/{database}"
print(uri)
postgresql://app_user:my%40pass%2Fword@localhost:5432/inventory
这个独立示例只会构建并打印 URI,不会连接到 PostgreSQL。若要让应用程序建立实际连接,请从运行环境中读取各项值,对 URI 组成部分进行编码,再将 URI 传给已安装的 psycopg2 软件包。代码中的英文提示和输出保持原样:
import os
from urllib.parse import quote
required = ("DB_USER", "DB_PASSWORD", "DB_HOST", "DB_PORT", "DB_NAME")
missing = [name for name in required if not os.environ.get(name)]
if missing:
print("Set the database environment variables before connecting.")
else:
try:
import psycopg2
import ipaddress
user = quote(os.environ["DB_USER"], safe="")
password = quote(os.environ["DB_PASSWORD"], safe="")
raw_host = os.environ["DB_HOST"]
try:
address = ipaddress.ip_address(raw_host)
except ValueError:
host = raw_host
else:
host = f"[{raw_host}]" if address.version == 6 else raw_host
port = os.environ["DB_PORT"]
database = quote(os.environ["DB_NAME"], safe="")
uri = f"postgresql://{user}:{password}@{host}:{port}/{database}"
connection = psycopg2.connect(uri)
connection.close()
print("Connected and closed the PostgreSQL connection.")
except Exception as error:
print(f"Connection was not completed ({type(error).__name__}).")
只有在五个变量均已设置且已安装 psycopg2 软件包时,第二个示例才会尝试连接数据库。将 DB_HOST 设置为 DNS 名称、IPv4 地址或未加方括号的 IPv6 字面地址;代码会为 URI authority 中的 IPv6 字面地址加上方括号,并保持 DNS 名称和 IPv4 地址不变。确认连接已打开后,示例会将其关闭。异常处理程序会以文本形式显示连接或配置错误;请在应用程序运行的环境中配置这些变量,不要将凭据写入源代码。代码中的英文提示和输出保持原样。
避免将凭据写入源代码
请将密码存放在环境变量或密钥管理器中,并避免将其提交到代码库、打印完整 URI,或将其写入日志和错误报告。例如,可以使用 Python 的 os.environ 读取 DB_USER、DB_PASSWORD、DB_HOST、DB_PORT 和 DB_NAME;使用 urllib.parse.quote(..., safe="") 对用户名、密码和数据库名称这些 URI 组成部分进行编码;然后组装 URI 并传给 psycopg2.connect(uri)。请在应用程序运行的环境中设置所需变量。只有当该环境中的服务器配置与预期相符时,才适合使用 localhost 或 5432 这样的默认值。
环境变量可以避免将密钥写入源文件,但仍需要设置适当的访问控制。不要用源代码中的常量代替密钥存储:常量无法隐藏其中的值。如果凭据已泄露,请更换它。
为远程连接配置 SSL
如果服务器要求加密连接,可将 sslmode=require 添加为 URI 查询参数,例如:postgresql://app_user:ENCODED_PASSWORD@db.example.test:5432/inventory?sslmode=require。如果 URI 已包含查询参数,请用 & 添加此参数,不要再使用第二个 ?。
sslmode=require 会要求加密,但单独使用时不会验证连接的服务器是否为预期服务器。若要验证服务器身份,请为客户端配置可信的证书颁发机构,并使用 sslmode=verify-full;该设置也会检查服务器名称。请遵循数据库运维方对证书和连接的要求。遇到证书错误时,不要在不了解后果的情况下关闭验证来绕过问题。
排查连接失败
可以按照以下顺序检查连接详情和服务器配置:
- **主机名或端口:**确认应用程序所在机器能够解析主机名、服务器正在指定地址和端口上监听,并且网络规则允许流量通过。
localhost指向应用程序运行的环境;该环境可能是容器或另一台主机,而不是你的工作站。 - **数据库或角色:**检查数据库名和用户名是否拼写正确,然后确认角色存在、密码仍然有效,并且拥有
CONNECT权限。身份验证和授权与网络是否可达是不同的问题。 - **URI 编码:**对用户名、密码和数据库路径中的保留字符进行百分号编码。例如,未编码的
@可能会被解析为主机名前的分隔符。 - **SSL 设置:**检查指定的
sslmode是否符合服务器策略。需要验证证书时,请检查配置的 CA 文件,并确保主机名与证书相符。 - **客户端配置:**确认应用程序读取了预期的环境变量,并使用了预期的 PostgreSQL 驱动程序。在 Python 中,
psycopg2可以通过psycopg2.connect(uri)接受 PostgreSQL URI;上面的 URI 打印示例只构建字符串,单独的环境变量示例才会尝试建立实际连接。
根据错误类别和服务器日志,判断问题属于网络超时、连接被拒绝、身份验证失败、数据库不存在,还是 TLS 验证问题。避免在诊断输出中分享完整连接字符串,因为其中可能包含凭据。