// 免费工具

PostgreSQL 连接字符串生成器

在一个表单里构建 PostgreSQL 连接 URI、libpq 关键字/值字符串、Npgsql(ADO.NET)字符串、JDBC URL 等;也可以粘贴其中任意一个,看看每个参数的作用,以及 sslmode 是否真的在保护你。 所有操作都在你的浏览器中运行:你输入的内容不会被发送到任何地方。

在 SQLly 中打开此连接

打开 SQLly 的连接编辑器并自动填入内容。

从设计上保护隐私。 构建器和解码器是运行在此标签页中的纯 JavaScript。页面不会把你输入的内容发送给任何服务器,不存储任何内容(甚至不存入浏览器),一旦加载完毕即可离线继续工作。“在 SQLly 中打开”链接会直接从浏览器跳转到你电脑上的应用。

PostgreSQL 连接字符串格式

大多数 PostgreSQL 驱动程序都基于 libpq 或复制其规则,因此 URI postgresql://user:password@host:5432/db?sslmode=verify-full 和关键字/值形式 host=... dbname=... 几乎在所有地方都能使用:psql、psycopg、pgx、lib/pq、node-postgres。Npgsql(.NET)和 pgJDBC(Java)有它们自己的写法。

最重要的参数是 sslmode。它的默认值, prefer,在服务器提供时使用 TLS,但从不检查证书,并会默默地回退到明文。只有 verify-full 会同时检查证书链和主机名。

URI libpq、psql、psycopg、pgx、node-postgres、Prisma

postgresql://app_user:[email protected]/sales?sslmode=verify-full

关键字/值 libpq conninfo、psycopg、pgx、lib/pq

host=db.example.com dbname=sales user=app_user password=your_password sslmode=verify-full

ADO.NET(Npgsql) Npgsql、Entity Framework Core

Host=db.example.com;Database=sales;Username=app_user;Password=your_password;SSL Mode=VerifyFull

JDBC PostgreSQL JDBC 驱动程序(pgJDBC)

jdbc:postgresql://db.example.com/sales?user=app_user&password=your_password&sslmode=verify-full

ODBC psqlODBC

Driver={PostgreSQL Unicode};Server=db.example.com;Database=sales;Uid=app_user;Pwd=your_password;SSLmode=verify-full;

SQLAlchemy URL 使用 psycopg 3 的 Python SQLAlchemy

postgresql+psycopg://app_user:[email protected]/sales?sslmode=verify-full

多个主机(故障转移) libpq 10+、pgx、Npgsql、pgJDBC

postgresql://[email protected]:5432,db2.example.com:5432/sales?target_session_attrs=read-write

占位符,例如 your_password 就是这样:用上面的表单自己拼一个连接字符串即可。更多关于将 SQLly 连接到 PostgreSQL 的信息: SQLly 适用于 PostgreSQL.

libpq 参数(URI 和关键字/值)

URI 形式: postgresql://[user[:password]@][host][:port][,...][/dbname][?param=value&...] (postgres:// 也可用);对特殊字符进行百分比编码,包括用作主机的 Unix 套接字路径的斜杠。关键字/值形式: key=value 用空格分隔的键值对;值为空或包含空格时用单引号括起来,并写入 \' 和 \\ ,用于转义其中的引号或反斜杠。

关键字同义词默认作用
host - /tmp 下的 Unix 套接字(Windows 上为 localhost) 主机名、IP 或 Unix 套接字目录。逗号分隔的列表会按顺序尝试。
hostaddr - - 数字 IP,跳过 DNS(主机仍用于 TLS 检查)。
port - 5432(构建默认值) 一个端口,或每个主机一个。
dbname - 用户名 要连接的数据库。
user - 操作系统用户 要连接的角色。
password - - 最好保存在 ~/.pgpass (或者 PGPASSWORD)比字符串里多。
passfile - ~/.pgpass(Windows 上为 %APPDATA%\postgresql\pgpass.conf) 密码文件。
connect_timeout - 0(永久等待) 每个主机的秒数。PostgreSQL 16 及更早版本会将 1 视为 2。
sslmode - prefer disable, allow, prefer, require, verify-ca, verify-full. require 仅在存在根证书文件时验证 CA;仅 verify-full 检查主机名。
sslrootcert - ~/.postgresql/root.crt CA 文件。 system (16+) 使用操作系统信任的 CA,并使 verify-full 默认值。
sslcert / sslkey - ~/.postgresql/postgresql.crt / .key 客户端证书和密钥。
sslnegotiation - postgres 17+. direct 立即启动 TLS(需要 sslmode 为 require 或更高)。
application_name - - 显示在 pg_stat_activity 和服务器日志中。
options - - 启动时的服务器设置,例如 -c statement_timeout=30000 -c search_path=app.
target_session_attrs - 任意 any, read-write, read-only, primary, standby, prefer-standby.
load_balance_hosts - 禁用 16+. random 打乱主机列表的顺序。
keepalives - 1 TCP 保活开/关;可通过以下选项调整: keepalives_idle, keepalives_interval, keepalives_count.
channel_binding - prefer require 拒绝在没有 SCRAM 通道绑定的情况下进行身份验证。

Npgsql(ADO.NET)参数

Npgsql 使用 ADO.NET Key=Value; 语法,关键字名称是它自己的一套。对包含 ; 带双引号。

关键字同义词默认作用
Host 服务器 - (必填) 主机名、IP、逗号分隔的列表,或以如下字符开头的套接字目录 /.
Port - 5432 TCP 端口。
Database 数据库 用户名 数据库名称。
Username User Name、User Id、UID PGUSER,否则使用操作系统用户 角色名称。
Password PSW,PWD PGPASSWORD 密码。
SSL Mode SslMode Prefer Disable, Allow, Prefer, Require, VerifyCA, VerifyFull。自 Npgsql 6 起, Require 不会验证证书。
Trust Server Certificate - 假的 跳过验证。Npgsql 6 和 7 需要使用 Require;Npgsql 8 则不需要。
Root Certificate - PGSSLROOTCERT 用于 VerifyCA / VerifyFull 的 CA 文件。
Timeout - 15 等待连接的秒数。
Command Timeout - 30 默认命令超时时间(秒);0 表示无限等待。
Application Name - PGAPPNAME application_name。
Search Path - - 模式搜索路径。
Target Session Attributes - 任意 any, primary, standby, prefer-primary, prefer-standby, read-write, read-only.
Pooling - true 连接池。
Maximum Pool Size - 100 最大连接池大小。
Minimum Pool Size - 0 最小的连接池。
Keepalive - 0(关闭) keepalive 查询之间的秒数。
Include Error Detail - 假的 将服务器错误详情(可能包含行数据)放入异常消息中。

pgJDBC 属性

URL 形式: jdbc:postgresql://host:port/database?property=value&...。pgJDBC 不会读取 user:password@ 在 URL 中:通过 user 和 password 作为参数或连接属性。

关键字同义词默认作用
user / password - - 凭证。
sslmode - prefer 与 libpq 相同的值。 require, allow 和 prefer 不会验证证书。
ssl - 假的 true 没有 sslmode 意味着 verify-full。
sslrootcert - ~/.postgresql/root.crt CA 文件。
connectTimeout - 10 等待套接字的秒数;0 表示不设限制。
socketTimeout - 0 读取可能阻塞的秒数;0 表示无限等待。
loginTimeout - 0 等待整个登录的秒数。
ApplicationName - PostgreSQL JDBC 驱动程序 application_name。
currentSchema - - search_path,以逗号分隔。
targetServerType - 任意 any, primary, secondary, preferPrimary, preferSecondary.
options - - 启动选项,例如 -c statement_timeout=30000 (在 URL 中进行百分比编码)。

常见的 PostgreSQL 连接错误

FATAL: no pg_hba.conf entry for host "10.0.0.7", user "app_user", database "sales", no encryption

原因: 服务器可以连通,但在 pg_hba.conf 允许此客户端、用户和数据库,或者匹配行是 hostssl 并且你是在未使用 TLS(“无加密”)的情况下连接的。

修复: 连接时使用 sslmode=require 或者如果服务器期望 TLS,则使用更强的,或者请管理员添加一行 host/hostssl 为你的地址加一行,然后重新加载服务器。

connection to server at "db.example.com" (10.0.0.5), port 5432 failed: Connection refused

原因: 该地址和端口上没有服务在监听:服务器已停止, listen_addresses 仅覆盖 localhost、端口不同,或防火墙拒绝了连接。

修复: 检查 listen_addresses 和 port 在 postgresql.conf 中、防火墙或云安全组中的设置,还要确认是否需要不同的端口(托管服务和连接池常用 6432 或自定义端口)。

FATAL: password authentication failed for user "app_user"

原因: 密码错误、角色没有密码,或密码中的特殊字符未在 URI 里做百分号编码,导致驱动程序读到的是另一个密码。

修复: 检查密码;在 URI 中需要把 @ 作为 %40, : 作为 %3A, / 作为 %2F 和 % 作为 %25。把 URI 粘贴到解码器里,就能确切看到驱动程序将发送哪个密码。

server does not support SSL, but SSL was required

原因: 该字符串要求 sslmode=require (或 verify-ca / verify-full)并且服务器具有 ssl = off.

修复: 在服务器上开启 TLS,或连接到提供商文档中给出的 TLS 端点。不要退回到 sslmode=disable 在你不控制的网络上。

root certificate file "/home/app/.postgresql/root.crt" does not exist

原因: sslmode=verify-ca 或者 verify-full 需要一个 CA 证书来进行验证,但 libpq 在默认路径下未找到任何证书。

修复: 下载你的服务商提供的 CA 证书包并设置 sslrootcert=/path/to/ca.pem,或者在 PostgreSQL 16+ 客户端使用 sslrootcert=system 当服务器的证书来自公共证书颁发机构时。

FATAL: database "app_user" does not exist

原因: 否 dbname 未提供,因此 libpq 把用户名当作数据库名。

修复: 将数据库添加到 URI 路径(/sales)或设置 dbname=sales.

invalid connection option "sslmod"

原因: 当关键字拼写错误或属于其他驱动程序时,libpq 会拒绝整个字符串(例如 ApplicationName 来自 pgJDBC 而不是 application_name).

修复: 修正拼写。解码器会列出每个 libpq 参数并标记未知参数。

PostgreSQL 连接字符串常见问题

PostgreSQL 连接字符串格式是什么?

基于 libpq 的驱动支持两种写法:URI postgresql://user:password@host:5432/dbname?sslmode=verify-full 和关键字/值字符串 host=host port=5432 dbname=dbname user=user sslmode=verify-full。Npgsql 使用 Host=...;Database=...;Username=... 而 Java 使用 jdbc:postgresql://host:5432/dbname.

应该使用哪种 sslmode?

verify-full 与 sslrootcert 指向你的 CA(或 system 在 PostgreSQL 16 及以上版本). require 会加密,但不验证应答方是谁,而 prefer,这是默认值,可能会悄悄回退到纯文本。请使用 disable 仅适用于套接字或 localhost。

如何在 PostgreSQL URI 中转义特殊字符?

在用户名、密码和数据库中对它们进行百分号编码: @ 是 %40, : 是 %3A, / 是 %2F, # 是 %23, ? 是 %3F, % 是 %25 和空格是 %20。关键字/值的形式能避开其中大部分麻烦:把值用单引号括起来,并转义 ' 和 \ 带反斜杠。

如何在连接字符串中设置语句超时?

对于基于 libpq 的驱动程序,添加 options=-c statement_timeout=30000 (毫秒;在 URI 中要把它百分号编码成 options=-c%20statement_timeout%3D30000)。Npgsql 有 Command Timeout,一个以秒为单位的客户端超时。

我可以列出多个主机来实现故障转移吗?

可以。写 postgresql://host1:5432,host2:5432/db 或者 host=host1,host2 port=5432,5432。libpq 会按顺序尝试它们;添加 target_session_attrs=read-write 以跳过只读备库,或者 load_balance_hosts=random (PostgreSQL 16+) 来分摊连接。

为什么 node-postgres 在 sslmode=require 时会验证证书?

pg-connection-string 目前会将 sslmode=prefer, require 和 verify-ca 作为 verify-full 并发出警告,说明在未来的主要版本中这一行为将改为 libpq 的含义。添加 uselibpqcompat=true 来立即改用 libpq 行为,或者配置 ssl 改在客户端配置中设置。

// 完全跳过这些字符串

连接一次。之后只管写 SQL。

SQLly 是适用于 macOS、Windows 和 Linux 的原生 SQL 工作台。在连接编辑器中粘贴连接字符串,把密码保存在系统钥匙串里,并在 PostgreSQL 等引擎上获得模式感知的 IntelliSense。