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