PostgreSQL-JDBC-驱动加载-初始化

导入JDBC

任何使用JDBC的源代码都需要导入java.sql包，使用以下代码：

import java.sql.*;

除非不使用标准的PostgreSQL™ JDBC API扩展，否则不应导入org.postgresql包。

加载驱动

应用程序不需要显式加载org.postgresql.Driver类，因为pgJDBC驱动程序jar支持Java服务提供者机制。只要驱动程序的jar文件位于类路径上，当应用程序连接到PostgreSQL™时，JVM将自动加载驱动程序。

在Java 1.6之前，驱动程序必须由应用程序加载-可以通过调用Class.forName("org.postgresql.Driver")来加载，也可以通过将驱动程序类名作为JVM参数

java -Djdbc.drivers=org.postgresql.Driver example.ImageViewer

来加载。

这些旧的驱动加载方法仍然受支持，但它们不再是必需的。

连接数据库

使用JDBC，数据库由URL（统一资源定位符）表示。在PostgreSQL中，URL可以有以下形式：

jdbc:postgresql:database

jdbc:postgresql:/

jdbc:postgresql://host/database

jdbc:postgresql://host/

jdbc:postgresql://host:port/database

jdbc:postgresql://host:port/

这些参数的含义如下：

• host = 服务器的主机名。默认为localhost。要指定IPv6地址，必须用方括号括起来，例如：jdbc:postgresql://[::1]:5740/accounting
• port = 服务器监听的端口号。默认为PostgreSQL™的标准端口号（5432）。
• database = 数据库名称。默认连接到与用户名相同的数据库。

要进行连接，您需要从JDBC获取一个Connection实例。

使用**DriverManager.getConnection()**方法：

Connection db = DriverManager.getConnection(url,username, password)

连接参数

除了标准的连接参数外，驱动程序还支持一些额外的属性，可以用于指定特定于PostgreSQL™的附加驱动程序行为。这些属性可以在连接URL或DriverManager.getConnection的附加Properties对象参数中指定。以下示例演示了使用这两种方法建立SSL连接的用法。

如果一个属性在URL和Properties对象中都有指定，则会忽略Properties对象中的值。

String url = "jdbc:postgresql://localhost/test";
Properties props = new Properties();
props.setProperty("user", "fred");
props.setProperty("password", "secret");
props.setProperty("ssl", "true");
Connection conn = DriverManager.getConnection(url, props);

String url = "jdbc:postgresql://localhost/test?user=fred&password=secret&ssl=true";
Connection conn = DriverManager.getConnection(url);

• user=String，是代表数据库连接的用户。
• password=String，是数据库用户的密码。
• options=String，指定“选项”连接初始化参数。例如，将其设置为**-c statement_timeout=5min**，将为此会话设置语句超时参数为5分钟。

property的值可能包含空格或其他特殊字符，如果在连接URL中提供，应该进行适当的编码。空格被认为是分隔命令行参数的字符，除非使用反斜杠（\）进行转义; \表示一个字面上的反斜杠。

Properties props = new Properties();
props.setProperty("options", "-c search_path=test,public,pg_catalog -c statement_timeout=90000");
Connection conn = DriverManager.getConnection(url, props);

String url = "jdbc:postgresql://localhost:5432/postgres?options=-c%20search_path=test,public,pg_catalog%20-c%20statement_timeout=90000";
Connection conn = DriverManager.getConnection(url);

• ssl (boolean)

使用SSL进行连接。服务器必须已经编译支持SSL。此属性不需要与任何值关联。其仅仅存在即指定了SSL连接。然而，为了与将来的版本兼容，更推荐使用“true”作为值。更多信息请参见使用SSL。

• sslfactory（String）

提供的值是用于建立SSL连接时使用的SSLSocketFactory类名。更多信息请参见“自定义SSLSocketFactory默认为LibPQFactory”部分。

• sslfactoryarg（String）：（已弃用）

此值是提供的sslfactory类的构造函数的可选参数。更多信息请参见“自定义SSLSocketFactory”部分。

• sslmode（String）

可能的值包括disable、allow、prefer、require、verify-ca和verify-full。require、allow和prefer都默认为非验证SSL工厂，并且不检查证书的有效性或主机名。verify-ca验证证书，但不验证主机名。verify-full将验证证书是否正确，并验证连接的主机与证书具有相同的主机名。默认值为prefer。设置这些值将需要在客户端机器上存储服务器证书，请参见配置客户端的详细信息。

• sslcert（String）

提供证书文件的完整路径。默认为/defaultdir/postgresql.crt，其中defaultdir是*nix系统中的${user.home}/.postgresql/，在Windows系统中为%appdata%/postgresql/。 它可以是PEM编码的X509v3证书。

在使用PKCS-12密钥时，该参数将被忽略，因为在这种情况下，证书也是从相同的密钥文件中检索的。

• sslkey（String）

提供密钥文件的完整路径。默认为/defaultdir/postgresql.pk8。

密钥文件必须以PKCS-12或PKCS-8 DER格式存在。可以使用openssl命令将PEM密钥转换为DER格式：openssl pkcs8 -topk8 -inform PEM -in postgresql.key -outform DER -out postgresql.pk8 -v1 PBE-MD5-DES

只有具有“.p12”（42.2.9+）或“.pfx”（42.2.16+）扩展名的PKCS-12密钥文件才会被识别。

如果您的密钥有密码，请使用下面描述的sslpassword连接参数提供密码。否则，您可以在上述命令中添加-nocrypt标志，以防止驱动程序请求密码。

在需要较高安全级别且密钥没有通过其他方式保护（如操作系统的访问控制）或密钥文件通过不受信任的通道传输的环境中，使用-v1 PBE-MD5-DES可能不足以满足要求。我们依赖于Java运行时提供的加密提供程序。本文档中记录的解决方案在撰写时已知可行。如果您有更严格的安全需求，请参考此处讨论该问题并选择更好的密码套件。

• sslrootcert（String）

SSL根证书的文件名。默认为defaultdir / root.crt。它可以是PEM编码的X509v3证书。

• sslhostnameverifier（String）

主机名验证器的类名。默认使用org.postgresql.ssl.PGjdbcHostnameVerifier。

• sslpasswordcallback（String）

SSL密码提供程序的类名。默认为org.postgresql.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler。

• sslpassword（String）

如果提供，将由ConsoleCallbackHandler使用。

• protocolVersion（int）

驱动程序支持V3前端/后端协议。V3协议在7.4中引入，并且驱动程序将默认尝试使用V3协议进行连接。

• loggerLevel（String）

该属性由驱动程序不再使用，将被忽略。所有日志配置由java.util.logging处理。

• loggerFile（String）

该属性由驱动程序不再使用，将被忽略。所有日志配置由java.util.logging处理。

• allowEncodingChanges (boolean)

在使用V3协议时，驱动程序会监视某些服务器配置参数的更改，这些参数不应由终端用户更改。client_encoding设置由驱动程序设置，并不应更改。如果驱动程序检测到更改，它将中止连接。然而，对于在服务器文件系统上存在的文件上使用COPY命令的情况，这种行为有一个合法的例外。指定该文件的编码的唯一方法是通过更改client_encoding设置。JDBC团队认为这是COPY命令的一个缺点，并希望未来能提供一种替代的方式来指定编码，但目前只能使用此URL参数。只有在进行复制时需要覆盖客户端编码时才启用此选项。

• logUnclosedConnections (boolean)

客户端可能会通过未调用其close()方法而泄漏Connection对象。最终，这些对象将被垃圾回收，并调用finalize()方法，如果调用者忽略了关闭连接，则会关闭Connection。使用终结器只是一种权宜之计。为了帮助开发人员检测和修正这些泄漏的源头，添加了logUnclosedConnections URL参数。它在每次打开连接时捕获堆栈跟踪，并且如果到达finalize()方法而未关闭连接，则将堆栈跟踪打印到日志中。

• autosave (String)

指定驱动程序在查询失败时应采取的操作。在autosave=always模式下，JDBC驱动程序在每个查询之前设置一个保存点，并在失败的情况下回滚到该保存点。在autosave=never模式（默认值）下，不会进行保存点操作。在autosave=conservative模式下，为每次查询设置保存点，但仅在罕见的情况下执行回滚，如“缓存的语句不能更改返回类型”或“语句XXX无效”，因此JDBC驱动程序回滚并重试。默认值为never。

• cleanupSavepoints (boolean)

确定是否在autosave模式下创建的保存点在语句之前释放。这样做是为了避免在执行数千个查询时服务器的共享缓冲区不足。默认值为'false'

• binaryTransfer (boolean)

如果可能，使用二进制格式发送和接收数据。默认值为'true'

• binaryTransferEnable (String)

启用二进制传输的类型的逗号分隔列表。可以是OID编号或名称。

• binaryTransferDisable (String)

禁用二进制传输的类型列表，以逗号分隔。可以使用OID数字或名称。覆盖默认设置和使用binaryTransferEnable设置的值。

• databaseMetadataCacheFields (int)

指定每个连接缓存的字段的最大数量。值为0禁用缓存。默认为65536。

• databaseMetadataCacheFieldsMiB (int)

指定每个连接缓存的字段的最大大小（以兆字节为单位）。值为0禁用缓存。默认为5。

• prepareThreshold (int)

确定在切换到使用服务器端预编译语句之前需要执行多少次PreparedStatement。默认值为5，意味着在同一个PreparedStatement对象的第五次执行之后开始使用服务器端预编译语句。有关服务器端预编译语句的更多信息，请参阅章节“服务器端预编译语句”。

• preparedStatementCacheQueries (int)

指定在每个连接中缓存的查询数量。默认值为256，这意味着如果在prepareStatement()调用中使用的查询超过256个不同的查询，则最近最少使用的查询将被丢弃。缓存使应用程序能够在每次执行后关闭预编译语句的情况下受益于服务器端预编译语句（参见prepareThreshold）。值为0禁用缓存。注意：每个连接都有自己的语句缓存。

• preparedStatementCacheSizeMiB (int)

确定预编译查询缓存的最大大小（以 mebibytes 为单位）（参考 preparedStatementCacheQueries）。默认值为5，意味着如果缓存的查询超过5 MiB，最近最少使用的查询将被丢弃。此设置的主要目的是防止 OutOfMemoryError。值为0表示禁用缓存。

• preferQueryMode (String)

指定执行与数据库的查询使用的模式：simple 表示（'Q' 执行，无解析，无绑定，仅文本模式），extended 表示始终使用 bind/execute 消息，extendedForPrepared 表示仅对预编译语句使用 extended 模式，extendedCacheEverything 表示使用扩展协议并尝试在查询缓存中缓存每个语句（包括 Statement.execute(String sql)）。extended | extendedForPrepared | extendedCacheEverything | simple。默认值为 extended。

• defaultRowFetchSize (int)

确定一次从数据库中获取的 ResultSet 行数。限制每次从数据库中获取的行数可以避免不必要的内存消耗，从而防止 OutOfMemoryError。默认值为零，表示 ResultSet 将一次性获取所有行。负数不可用。

• loginTimeout (int)

指定等待建立数据库连接的时间。超时时间以秒为单位。

• connectTimeout (int)

用于套接字连接操作的超时值。如果连接到服务器的时间超过此值，则连接将断开。超时时间以秒为单位，零表示禁用超时。

• socketTimeout (int)

用于套接字读取操作的超时值。如果从服务器读取的时间超过此值，则连接将关闭。这既可以用作强制全局查询超时的方法，也可以用作检测网络问题的方法。超时时间以秒为单位，零表示禁用超时。

• cancelSignalTimeout (int)

取消命令通过自己的连接发送，但是取消消息本身可能会被卡住。此属性控制用于取消命令的“连接超时”和“套接字超时”。超时时间以秒为单位。默认值为10秒。

• tcpKeepAlive (boolean)

启用或禁用TCP保活探测。默认值为false。

• tcpNoDelay (boolean)

启用或禁用TCP无延迟。默认值为true。

• unknownLength (int)

某些PostgreSQL类型（如TEXT）不具有明确定义的长度。当通过ResultSetMetaData.getColumnDisplaySize和ResultSetMetaData.getPrecision等函数返回关于这些类型的元数据时，我们必须提供一个值，而各种客户端工具对于他们想要看到什么有不同的想法。该参数指定返回未知长度类型的长度。

• stringtype (String)

通过setString()方法绑定PreparedStatement参数时指定要使用的类型。如果stringtype设置为VARCHAR（默认值），这些参数将作为varchar参数发送到服务器。如果stringtype设置为未指定，则参数将作为未类型化的值发送到服务器，并且服务器将尝试推断适当的类型。如果您有一个现有的应用程序使用setString()方法设置实际上是其他类型（如整数）的参数，并且无法更改应用程序以使用适当的方法（如setInt()），这将很有用。

• ApplicationName (String)

指定使用连接的应用程序的名称。这允许数据库管理员通过像pg_stat_activity这样的视图看到哪些应用程序连接到服务器并且使用了哪些资源。

• kerberosServerName (String)

在使用GSSAPI进行身份验证时使用的Kerberos服务名称。这相当于libpq的PGKRBSRVNAME环境变量，其默认值为“postgres”。

• jaasApplicationName (String)

指定JAAS系统或应用程序登录配置的名称。

• jaasLogin (boolean)

指定是否在使用GSSAPI进行身份验证之前执行JAAS登录。如果设置为true（默认值），驱动程序将尝试使用配置的JAAS登录模块（例如Krb5LoginModule）获取GSS凭据，然后进行身份验证。如果要跳过JAAS登录，例如如果使用原生GSS实现来获取凭据，则将其设置为false。

• gssEncMode（String）

PostgreSQL 12及更高版本现在允许使用GSSAPI加密连接。此参数控制是否强制使用GSSAPI加密。选项是disable（禁用）、allow（允许）、prefer（优先）和require（要求）。

disable是明显的，禁止使用GSS加密模式连接。
allow将以明文方式连接，然后如果服务器要求，将切换到加密模式。
prefer将尝试以加密模式连接，如果无法获取加密连接，则回退到明文。
require尝试以加密模式连接，并在无法连接时失败。默认值为allow。

• gsslib（字符串）

在服务器要求Kerberos或SSPI身份验证时，强制使用SSPI（Windows透明单点登录）或GSSAPI（通过JSSE的Kerberos）。允许的值为auto（默认值，见下文）、sspi（强制使用SSPI）或gssapi（强制使用GSSAPI-JSSE）。如果此参数为auto，则如果服务器要求SSPI身份验证、JDBC客户端在Windows上运行，并且CLASSPATH中包含所需的Waffle库，则尝试使用SSPI。否则，将使用Kerberos/GSSAPI通过JSSE。

这种行为与libpq的行为并不完全相同，在Windows上默认情况下，libpq在Kerberos（GSSAPI）请求时使用Windows的SSPI库。

gssapi模式强制使用JSSE的GSSAPI，即使有SSPI也可用，与9.4版本之前的行为相匹配。

在非Windows平台或无法使用SSPI的情况下，强制使用sspi模式将导致PSQLException错误。要在PgJDBC中使用SSPI，必须确保在CLASSPATH中存在waffle-jna库及其依赖项。pgJDBC不在pgJDBC jar中捆绑waffle-jna。

Since: 9.4

• sspiServiceClass (String)

指定Windows SSPI服务类的名称，该名称是SPN的服务类部分。默认值POSTGRES几乎总是正确的。请参阅：SSPI身份验证（Pg文档）服务主体名称（MSDN），DsMakeSpn（MSDN）配置SSPI（Pg wiki）。在非Windows平台上，忽略此参数。

• useSpnego（boolean）

在SSPI身份验证请求中使用SPNEGO

• sendBufferSize（int）

设置连接流的SO_SNDBUF

• receiveBufferSize（int）

设置连接流的SO_RCVBUF

• readOnly（boolean）

将连接设置为只读模式

• readOnlyMode（String）

其中之一是'ignore'，'transaction'或'always'。控制连接设置为只读时的行为，当设置为'ignore'时，readOnly设置不起作用。当设置为'transaction'且readOnly设置为'true'且autocommit为'false'时，驱动程序将通过发送BEGIN READ ONLY将事务设置为只读。当设置为'always'且readOnly设置为'true'时，如果autoCommit为'true'，会将会话设置为只读。如果autocommit为false，则驱动程序将通过发送BEGIN READ ONLY将事务设置为只读。默认值是'transaction'

• disableColumnSanitiser（boolean）

将其设置为true可以禁用列名清洗器。清洗器将结果集中的列折叠为小写。默认情况下，对列进行清洗（关闭）。

• assumeMinServerVersion（String）

假设服务器至少为给定版本，从而在连接时启用一些优化，而不是尝试版本盲目。

• currentSchema（String）

指定要在搜索路径中设置的模式（或用逗号分隔的多个模式）。此模式将用于解析在此连接上使用的未限定对象名的语句。

• targetServerType（String）

允许仅打开具有所需状态的服务器的连接，允许的值为any、primary、master、slave、secondary、preferSlave、preferSecondary和preferPrimary。主/从区分目前通过观察服务器是否允许写入来完成。值preferSecondary尝试连接到可用的次要服务器，否则将回退到连接到主服务器。值preferPrimary尝试连接到可用的主服务器，否则将回退到连接到可用的次要服务器。

• hostRecheckSeconds（int）

控制主机状态信息在JVM全局缓存中缓存多长时间（以秒为单位）。默认值为10秒。

• loadBalanceHosts（boolean）

在默认模式下（禁用时），主机按照给定的顺序连接。如果启用，则从合适的候选主机集合中随机选择主机。

• socketFactory（String）

提供的值是在建立套接字连接时用作SocketFactory的类名。这可以用来创建Unix套接字而不是普通套接字。由socketFactory指定的类名必须扩展javax.net.SocketFactory，并且对驱动程序的类加载器可用。此类必须具有零参数构造函数、一个带有字符串参数的单参数构造函数或一个带有Properties参数的单参数构造函数。Properties对象将包含所有连接参数。socketFactoryArg连接参数的值将作为String参数传递。

• socketFactoryArg（String）：（已过时）

这个值是提供的socket工厂类的构造函数的可选参数。

• reWriteBatchedInserts（boolean）

这将把批量插入从insert into foo（col1，col2，col3）values（1，2，3）更改为insert into foo（col1，col2，col3）values（1，2，3），（4，5，6），这提供了2-3倍的性能提升。

• replication（String）

在启动消息中传递的连接参数。该参数接受两个值：“true”和“database”。传递true告诉后端进入walsender模式，在该模式下可以发出一小组复制命令而不是SQL语句。只有简单的查询协议可以在walsender模式下使用。将“database”作为值传递给walsender，指示其连接到dbname参数中指定的数据库，这将允许该连接用于从该数据库进行逻辑复制。参数应与assumeMinServerVersion一起使用，参数大于等于9.4（后端大于等于9.4）。

• escapeSyntaxCallMode (String) Specifies how the driver transforms JDBC escape call syntax into underlying SQL, for invoking procedures or functions. In escapeSyntaxCallMode=select mode (the default), the driver always uses a SELECT statement (allowing function invocation only). In escapeSyntaxCallMode=callIfNoReturn mode, the driver uses a CALL statement (allowing procedure invocation) if there is no return parameter specified, otherwise the driver uses a SELECT statement. In escapeSyntaxCallMode=call mode, the driver always uses a CALL statement (allowing procedure invocation only). The default is select
• maxResultBuffer（String）

指定结果缓冲区的大小（以字节为单位），在读取结果集期间不能超过该大小。属性可以以两种方式指定：

作为字节大小（例如100，150M，300K，400G，1T）；
作为最大堆内存的百分比（例如10p，15pct，20percent）；在设置属性时的限制是最大堆内存的90％。所有给定的值，如果超过限制，都将降低到限制值。默认情况下，maxResultBuffer未设置（为null），这意味着读取结果将在没有限制的情况下执行。

• adaptiveFetch（boolean）

指定在ResultSet中通过一次向数据库的请求获取的行数是否应该是动态的。使用自适应获取计算的动态行数，可以充分利用maxResultBuffer属性中声明的大部分缓冲区。行数将通过将maxResultBuffer大小除以迄今为止的最大行大小并向下取整来计算。第一次获取将具有在defaultRowFetchSize中声明的行数。行数可以通过adaptiveFetchMinimum和adaptiveFetchMaximum来限制。需要声明maxResultBuffer和defaultRowFetchSize才能工作。默认情况下，adaptiveFetch为false。

• adaptiveFetchMinimum（int）

指定可以由adaptiveFetch计算的最低行数。需要将adaptiveFetch设置为true才能工作。默认情况下，由adaptiveFetch计算的最小行数为0。

• adaptiveFetchMaximum（int）

指定可以由adaptiveFetch计算的最大行数。需要将adaptiveFetch设置为true才能工作。默认情况下，由adaptiveFetch计算的最大行数为-1，表示无限大。

• logServerErrorDetail（boolean）

是否在异常和日志消息中包含服务器错误的详细信息（例如内联查询参数）。将其设置为false将仅包含最小的、不敏感的消息。默认情况下，该值设置为true，服务器错误详细信息会传播。这可能包含敏感信息，如查询参数。

• quoteReturningIdentifiers（boolean）

引用返回列。有一些ORM会引用所有内容，包括返回列。如果我们引用它们，那么我们发送到后端的将是““colname””而非“colname”，这将导致找不到。

• authenticationPluginClassName（String）

实现AuthenticationPlugin接口的类的完全限定类名。如果为null，则使用连接属性中的密码值。

Unix sockets

通过添加junixsocket，您可以获得与驱动程序配合使用的套接字工厂。代码可以在这里找到，并且说明可以在这里找到。

依赖项为：

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-core</artifactId>
  <version>2.3.3</version>
</dependency>

只需将

?socketFactory=org.newsclub.net.unix.AFUNIXSocketFactory$FactoryArg&socketFactoryArg=[path-to-the-unix-socket]

添加到连接URL中。

对于许多发行版，默认路径是 /var/run/postgresql/.s.PGSQL.5432。

连接故障切换

为了支持简单的连接故障转移，可以在连接URL中通过逗号分隔定义多个端点（主机和端口）。驱动程序将按顺序尝试连接到每个端点，直到连接成功为止。如果没有端点成功连接，将抛出正常的连接异常。

连接URL的语法是：jdbc:postgresql://host1:port1,host2:port2/database

简单的连接故障转移在针对具有相同数据的高可用性PostgreSQL安装时很有用。例如，流复制PostgreSQL或PostgreSQL-XC集群。

例如，应用程序可以创建两个连接池。一个数据源用于写入操作，另一个用于读取操作。写入池仅限于主节点的连接：

jdbc:postgresql://node1,node2,node3/accounting?targetServerType=primary

读取池在从节点之间平衡连接，但如果没有可用的从节点，则允许连接到主节点：jdbc:postgresql://node1,node2,node3/accounting?targetServerType=preferSecondary&loadBalanceHosts=true

如果一个从节点失败，将首先尝试所有在列表中的从节点。如果没有可用的从节点，将尝试主节点。如果缓存中的所有服务器都被标记为“无法连接”，则将按顺序尝试连接URL中的所有主机。