当前位置：首页 > news >正文

PostgreSQL JDBC 连接参数大全

news 2025/10/13 6:30:58

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);

重要提示：