PostgreSQL JDBC 连接参数大全

PostgreSQL JDBC 驱动提供了非常丰富的连接参数，允许你精细地控制连接行为、性能和安全设置。这些参数通常以 URL 参数的形式传递，格式为：

jdbc:postgresql://host:port/database?param1=value1&param2=value2&...

或者通过 Properties 对象设置。

下面是一个分类整理的参数大全，包含常用参数和许多高级参数。

---

一、 基础连接参数

参数名	描述	示例值	默认值
user	连接数据库的用户名	myuser	-
password	连接数据库的密码	mypass	-
database	要连接的数据库名（也可以在 URL 路径中指定）	mydb	与用户名相同
host	数据库服务器地址（也可以在 URL 主机部分指定）	localhost	localhost
port	数据库服务器端口（也可以在 URL 端口部分指定）	5432	5432
sslmode	SSL 连接模式，控制安全级别	disable， require， verify-ca， verify-full	prefer
ssl	已废弃，建议使用 sslmode	true， false	false

---

二、 连接池与超时控制

参数名	描述	示例值	默认值
loginTimeout	建立连接的超时时间（秒）	10	0（无限）
connectTimeout	建立 TCP 连接的超时时间（秒）	10	0（无限）
socketTimeout	Socket 读操作的超时时间（秒）。0 表示禁用。	60	0（无限）
tcpKeepAlive	是否启用 TCP Keep-Alive	true， false	false
cancelSignalTimeout	取消命令的超时时间（秒）	10	10
loadBalanceHosts	在多个主机间随机选择连接，而不是按顺序。	true， false	false
targetServerType	指定希望连接到哪种类型的服务器。	any， master， slave， preferSlave等	any

---

三、 性能与网络相关

参数名	描述	示例值	默认值
application_name	设置客户端应用名称，在 pg_stat_activity 中可见	MyApp	-
readOnly	将连接设置为只读模式	true， false	false
prepareThreshold	一个语句被执行多少次后会被服务器端预处理	5	5
preparedStatementCacheQueries	每个连接预编译语句缓存的大小	256	256
preparedStatementCacheSizeMiB	预编译语句缓存的最大内存（MB）	5	5
defaultRowFetchSize	设置从游标中一次获取的行数，影响 ResultSet 性能	100	0（一次性获取所有）
receiveBufferSize	TCP 接收缓冲区大小（字节）	-1（使用系统默认）	-1
sendBufferSize	TCP 发送缓冲区大小（字节）	-1（使用系统默认）	-1
binaryTransfer	是否使用二进制格式传输数据（某些类型）	true， false	true
binaryTransferEnable	为指定数据类型启用二进制传输	oid1，oid2,...	-
binaryTransferDisable	为指定数据类型禁用二进制传输	oid1，oid2,...	-
stringtype	当设置 PreparedStatement 的 setString 方法时，如何对待参数。	unspecified， varchar	unspecified

---

四、 日志与调试

参数名	描述	示例值	默认值
loggerLevel	设置 JDBC 驱动的日志级别	OFF， DEBUG， TRACE	OFF
loggerFile	指定日志输出文件	/tmp/pgjdbc.log	-
logUnclosedConnections	当连接未被关闭而被垃圾回收时，是否记录警告	true， false	false
allowEncodingChanges	是否允许在连接过程中改变客户端编码	true， false	false
debugLevel	已废弃，请使用 loggerLevel	-	-

---

五、 SSL/TLS 安全相关

参数名	描述	示例值	默认值
sslcert	客户端 SSL 证书文件路径	/path/to/client.crt	-
sslkey	客户端 SSL 私钥文件路径	/path/to/client.pk8	-
sslpassword	客户端 SSL 私钥的密码（如果有）	keypassword	-
sslpasswordcallback	用于获取私钥密码的类名（实现 PGPropertyPasswordCallback）	com.myapp.CustomPasswordCallback	-
sslrootcert	SSL CA 证书文件路径，用于验证服务器证书	/path/to/root.crt	-
sslfactory	自定义 SSLSocketFactory 类名	com.myapp.CustomSSLSocketFactory	-
sslfactoryarg	传递给自定义 SSLSocketFactory 的参数	arg	-
sslhostnameverifier	自定义 HostnameVerifier 类名	com.myapp.CustomVerifier	-
sslmode	（再次强调） 控制 SSL 行为的安全级别	verify-full	prefer

---

六、 认证与 Kerberos

参数名	描述	示例值	默认值
gsslib	使用 GSSAPI 认证时，选择使用原生实现还是纯 Java 实现	auto， sspi（Windows）， gssapi（Unix）	auto
jaasApplicationName	JAAS 配置的登录模块名	pgjdbc	pgjdbc
jaasLogin	是否使用 JAAS 登录	true， false	true
kerberosServerName	Kerberos 服务主体名称	postgres	postgres
useSpnego	是否使用 SPNEGO 进行 GSSAPI 认证	true， false	false

---

七、 其他高级参数

参数名	描述	示例值	默认值
currentSchema	设置连接后的默认模式（schema）	my_schema	public
options	在连接启动时发送给后端的命令行选项	-c statement_timeout=10000	-
assumeMinServerVersion	假定服务器至少是这个版本，绕过某些版本检测	9.0， 10.5	-
protocolVersion	强制使用特定的前后端协议版本	2， 3	0（自动）
readOnlyMode	已废弃，使用 readOnly	-	-
disableColumnSanitiser	禁用列名的大小写转换（转为小写）	true， false	false
autosave	当语句执行失败时（如 "cached plan must not change result type"），自动重试的策略。	conservative， never， always	never
cleanupSavepoints	在事务提交/回滚后是否自动释放保存点	true， false	false
reWriteBatchedInserts	将批量插入 insert into foo values(1)，(2)，(3)... 重写为更高效的 insert into foo values (1)，(2)，(3)...	true， false	false

---

使用示例

1. URL 方式

String url = "jdbc:postgresql://localhost:5432/mydb?"
    + "user=myuser&password=mypass"
    + "&sslmode=verify-full"
    + "&sslrootcert=/path/to/ca.crt"
    + "&defaultRowFetchSize=100"
    + "&application_name=MyApp"
    + "&connectTimeout=10"
    + "&socketTimeout=60";
Connection conn = DriverManager.getConnection(url);

2. Properties 方式

String url = "jdbc:postgresql://localhost:5432/mydb";
Properties props = new Properties();
props.setProperty("user", "myuser");
props.setProperty("password", "mypass");
props.setProperty("sslmode", "verify-full");
props.setProperty("sslrootcert", "/path/to/ca.crt");
props.setProperty("application_name", "MyApp");
Connection conn = DriverManager.getConnection(url, props);

重要提示：

• 官方文档是获取最新、最准确参数列表的最佳来源：PostgreSQL JDBC 连接参数官方文档。

• 参数名称是大小写敏感的。

• 并非所有参数都适用于所有版本的服务器和驱动，请根据1、的环境进行测试。