HikariCP資料庫連線池中文使用手冊

2020-09-19 16:01:06

HikariCP 資料庫連線池


迄今為止,效能最好,速度最快的資料庫連線池。

 

依賴項


Java 8 thru 11 maven artifact:


    <dependency>
        <groupId>com.zaxxer</groupId>
        <artifactId>HikariCP</artifactId>
        <version>3.4.5</version>
    </dependency>


Java 7 maven artifact (maintenance mode):


    <dependency>
        <groupId>com.zaxxer</groupId>
        <artifactId>HikariCP-java7</artifactId>
        <version>2.4.13</version>
    </dependency>


Java 6 maven artifact (maintenance mode):


    <dependency>
        <groupId>com.zaxxer</groupId>
        <artifactId>HikariCP-java6</artifactId>
        <version>2.3.13</version>
    </dependency>

HikariCP的jdbc驅動名和資料來源類名對應列表


Here is a list of JDBC DataSource classes for popular databases:
Database             Driver              DataSource class
Apache Derby      Derby                 org.apache.derby.jdbc.ClientDataSource
Firebird                 Jaybird               org.firebirdsql.ds.FBSimpleDataSource
H2                         H2                      org.h2.jdbcx.JdbcDataSource
HSQLDB               HSQLDB            org.hsqldb.jdbc.JDBCDataSource
IBM                       DB2   IBM JCC   com.ibm.db2.jcc.DB2SimpleDataSource
IBM Informix         IBM Informix       com.informix.jdbcx.IfxDataSource
MS SQL Server    Microsoft             com.microsoft.sqlserver.jdbc.SQLServerDataSource
MySQL                 Connector/J         com.mysql.jdbc.jdbc2.optional.MysqlDataSource
MariaDB               MariaDB              org.mariadb.jdbc.MariaDbDataSource
Oracle                  Oracle                  oracle.jdbc.pool.OracleDataSource
OrientDB              OrientDB             com.orientechnologies.orient.jdbc.OrientDataSource
PostgreSQL          pgjdbc-ng            com.impossibl.postgres.jdbc.PGDataSource
PostgreSQL          PostgreSQL        org.postgresql.ds.PGSimpleDataSource
SAP MaxDB         SAP                     com.sap.dbtech.jdbc.DriverSapDB
SQLite                  xerial                   org.sqlite.SQLiteDataSource
SyBase                 jConnect             com.sybase.jdbc4.jdbc.SybDataSource

補充(實際上postgreSQL官方jdbc驅動使用下面這個類名):
PostgreSQL    PostgreSQL    org.postgresql.Driver

 

HikariCP設定屬性全覽


HikariCP帶有合理的預設值,在大多數部署中都可以正常執行,而無需進行其他調整。每個屬性都是可選的,但以下標記的「必需」除外。

📎HikariCP使用毫秒作為所有時間值。
HikariCP依靠準確的計時器來提高效能和可靠性。您的伺服器必須與時間源(例如NTP伺服器)同步。特別是如果您的伺服器在虛擬機器器中執行。為什麼?在這裡閱讀更多。不要依靠虛擬機器器監控程式設定來「同步」虛擬機器器的時鐘。在虛擬機器器內部設定時間源同步。如果您是由於時間缺乏同步而尋求支援,則會在Twitter上公開嘲諷您。

這個是真的,如果因為時間漂移問題導致無法獲取連線這個問題去問作者會被噴。

Essentials(必需的設定)
🔠dataSourceClassName
這是JDBC驅動程式提供的DataSource類的名稱。有關特定的JDBC驅動程式的資訊,請查閱檔案以獲取該類名,或參閱下表。注意不支援XA資料來源。 XA需要像bitronix這樣的真實事務管理器。請注意,如果您使用jdbcUrl進行基於「老式」基於DriverManager的JDBC驅動程式設定,則不需要此屬性。預設值:無

- 或 -

🔠jdbcUrl
此屬性指示HikariCP使用「基於DriverManager的」設定。我們認為基於資料來源的設定(上文)優於多種原因(請參見下文),但是對於許多部署而言,差異不大。當將此屬性與「舊」驅動程式一起使用時,您可能還需要設定driverClassName屬性,但首先嚐試不使用該屬性。請注意,如果使用此屬性,則仍可以使用DataSource屬性來設定驅動程式,實際上,建議您對URL本身中指定的驅動程式引數進行推薦。預設值:無

實際上,大部分實際應用中,HikariCP都不能通過jdbcUrl解析出正確的driverClassName,所以我認為driverClassName是必須的,所以我把driverClassName從不常用設定提升到必須設定。

🔠driverClassName
HikariCP將嘗試僅通過jdbcUrl通過DriverManager來解析驅動程式,但是對於某些較舊的驅動程式,還必須指定driverClassName。除非獲得明顯的錯誤訊息指示未找到驅動程式,否則請忽略此屬性。預設值:無

🔠username(使用者名稱)
此屬性設定從基礎驅動程式獲取連線時使用的預設身份驗證使用者名稱。請注意,對於DataSources,這可以通過在基礎DataSource上呼叫DataSource.getConnection(* username *,password)以非常確定的方式進行。但是,對於基於驅動程式的設定,每個驅動程式都是不同的。對於基於驅動程式的情況,HikariCP將使用此使用者名稱屬性在傳遞給驅動程式的DriverManager.getConnection(jdbcUrl,props)呼叫的屬性中設定使用者屬性。如果這不是您所需要的,請完全跳過此方法,並例如呼叫addDataSourceProperty(「 username」,...)。預設值:無

🔠password(密碼)
此屬性設定從基礎驅動程式獲取連線時使用的預設身份驗證密碼。請注意,對於DataSources,這可以通過在基礎DataSource上呼叫DataSource.getConnection(username,* password *)以非常確定的方式進行。但是,對於基於驅動程式的設定,每個驅動程式都是不同的。對於基於驅動程式的情況,HikariCP將使用此密碼屬性在傳遞給驅動程式的DriverManager.getConnection(jdbcUrl,props)呼叫的屬性中設定密碼屬性。如果這不是您所需要的,請完全跳過此方法,例如,呼叫addDataSourceProperty(「 pass」,...)。預設值:無

Frequently used(以下是經常使用的設定屬性)

autoCommit
此屬性控制從池返回的連線的預設自動提交行為。它是一個布林值。預設值:true

⌚connectionTimeout
此屬性控制使用者端(即您)等待來自池的連線的最大毫秒數。如果超過此時間而沒有可用的連線,則會丟擲SQLException。可接受的最低連線超時為250 ms。預設值:30000(30秒)

⌚idleTimeout
此屬性控制允許連線在池中保持空閒狀態的最長時間。僅當minimumIdle定義為小於maximumPoolSize時,此設定才適用。一旦池達到MinimumIdle連線,空閒連線將不被取消。連線是否以空閒狀態退役,最大變化為+30秒,平均變化為+15秒。在此超時之前,連線永遠不會因為空閒而退役。值為0表示永遠不會從池中刪除空閒連線。最小允許值為10000ms(10秒)。預設值:600000(10分鐘)

⌚maxLifetime(最大生存時間)
此屬性控制池中連線的最大生存期。使用中的連線永遠不會退出,只有在關閉連線後才將其刪除。在逐個連線的基礎上,應用較小的負衰減以避免池中的品質消滅。我們強烈建議設定此值,它應該比任何資料庫或基礎結構施加的連線時間限制短几秒鐘。值0表示沒有最大生存期(無限生存期),當然要遵守idleTimeout設定。最小允許值為30000ms(30秒)。預設值:1800000(30分鐘)

connectionTestQuery(連線測試查詢)
如果您的驅動程式支援JDBC4,我們強烈建議不要設定此屬性。這是針對不支援JDBC4 Connection.isValid()API的「舊版」驅動程式的。這是將在從池中為您提供連線之前執行的查詢,以驗證與資料庫的連線仍然有效。同樣,嘗試執行不帶該屬性的池,如果驅動程式不相容JDBC4,HikariCP將記錄錯誤。預設值:無

🔢minimumIdle(最小空閒連線數)
此屬性控制HikariCP嘗試在池中維護的最小空閒連線數。如果空閒連線下降到該值以下,並且池中的總連線數小於maximumPoolSize,則HikariCP將盡最大努力快速而有效地新增其他連線。但是,為了獲得最佳效能和對峰值需求的響應能力,建議不要設定該值,而應讓HikariCP充當固定大小的連線池。預設值:與maximumPoolSize相同

🔢maximumPoolSize(最大空閒連線數)
此屬性控制允許池達到的最大大小,包括空閒和使用中的連線。基本上,此值將確定到資料庫後端的最大實際連線數。合理的值最好由您的執行環境確定。當池達到此大小,並且沒有空閒連線可用時,在超時之前,對getConnection()的呼叫將最多阻塞connectionTimeout毫秒。請閱讀有關池大小的資訊。預設值:10

📈metricRegistry
此屬性僅可通過程式設計設定或IoC容器使用。此屬性允許您指定Codahale / Dropwizard MetricRegistry的範例,池將使用該範例來記錄各種指標。有關詳細資訊,請參見Metrics Wiki頁面。預設值:無

📈healthCheckRegistry
此屬性僅可通過程式設計設定或IoC容器使用。此屬性允許您指定Codahale / Dropwizard HealthCheckRegistry的範例,池將使用該範例來報告當前的健康資訊。有關詳細資訊,請參見執行狀況檢查Wiki頁面。預設值:無

🔠poolName
該屬性表示連線池的使用者定義名稱,主要出現在紀錄檔記錄和JMX管理控制檯中,以識別池和池設定。預設值:自動生成

Infrequently used(以下是很少的使用設定屬性)
⌚initializationFailTimeout
此屬性控制如果無法為初始連線成功播種池,則池是否將「快速失敗」。任何正數都將視為嘗試獲取初始連線的毫秒數;在此期間,應用程式執行緒將被阻止。如果在此超時發生之前無法獲取連線,則將引發異常。此超時在connectionTimeout時間段之後應用。如果值為零(0),則HikariCP將嘗試獲取並驗證連線。如果獲得連線但驗證失敗,則將引發異常並且池不啟動。但是,如果無法獲得連線,則池將啟動,但是以後獲得連線的努力可能會失敗。小於零的值將繞過任何初始連線嘗試,並且池將在嘗試在後臺獲取連線時立即啟動。因此,以後獲得連線的努力可能會失敗。預設值:1

❎isolateInternalQueries
此屬性確定HikariCP是否在其自身的事務中隔離內部池查詢,例如連線活動測試。由於這些通常是唯讀查詢,因此幾乎沒有必要將它們封裝在自己的事務中。僅當禁用autoCommit時,此屬性才適用。預設值:false

❎allowPoolSuspension
此屬性控制是否可以通過JMX暫停和恢復池。這對於某些故障轉移自動化方案很有用。當池掛起時,對getConnection()的呼叫不會超時,並且將保持到恢復池為止。預設值:false

❎readOnly
此屬性控制預設情況下從池獲得的連線是否處於唯讀模式。請注意,某些資料庫不支援唯讀模式的概念,而另一些資料庫在將Connection設定為唯讀時提供查詢優化。是否需要此屬性在很大程度上取決於您的應用程式和資料庫。預設值:false

❎registerMbeans
此屬性控制是否註冊JMX管理Bean(「 MBean」)。預設值:false

🔠catalog
此屬性為支援目錄概念的資料庫設定預設目錄。如果未指定此屬性,則使用JDBC驅動程式定義的預設目錄。預設值:驅動程式預設值

🔠connectionInitSql
此屬性設定一個SQL語句,該語句將在每次建立新連線後執行,然後再將其新增到池中。如果此SQL無效或引發異常,它將被視為連線失敗,並且將遵循標準的重試邏輯。預設值:無

 

transactionIsolation
此屬性控制從池返回的連線的預設事務隔離級別。如果未指定此屬性,則使用JDBC驅動程式定義的預設事務隔離級別。僅當您具有所有查詢通用的特定隔離要求時,才使用此屬性。此屬性的值是Connection類中的常數名稱,例如TRANSACTION_READ_COMMITTED,TRANSACTION_REPEATABLE_READ等。預設值:驅動程式預設值

⌚validationTimeout
此屬性控制將測試連線的活動性的最長時間。此值必須小於connectionTimeout。可接受的最低驗證超時為250毫秒。預設值:5000

⌚leakDetectionThreshold
此屬性控制在記錄表示可能的連線洩漏的訊息之前,連線可以離開池的時間。值為0表示禁用洩漏檢測。啟用洩漏檢測的最低可接受值為2000(2秒)。預設值:0

➡dataSource
此屬性僅可通過程式設計設定或IoC容器使用。此屬性使您可以直接設定要由池包裝的DataSource範例,而不是讓HikariCP通過反射構造它。這在某些依賴項注入框架中可能很有用。指定此屬性後,將忽略dataSourceClassName屬性和所有特定於DataSource的屬性。預設值:無

🔠schema
此屬性為支援模式概念的資料庫設定預設模式。如果未指定此屬性,則使用JDBC驅動程式定義的預設模式。預設值:驅動程式預設值

➡threadFactory
此屬性僅可通過程式設計設定或IoC容器使用。此屬性允許您設定java.util.concurrent.ThreadFactory的範例,該範例將用於建立池使用的所有執行緒。在某些只能通過應用程式容器提供的ThreadFactory建立執行緒的受限執行環境中,需要使用它。預設值:無

➡scheduledExecutor
此屬性僅可通過程式設計設定或IoC容器使用。該屬性允許您設定java.util.concurrent.ScheduledExecutorService的範例,該範例將用於各種內部計劃的任務。如果向HikariCP提供ScheduledThreadPoolExecutor範例,則建議使用setRemoveOnCancelPolicy(true)。預設值:無

 

在spring設定中如何初始化HikariCP的datasource

使用com.zaxxer.hikari.HikariDataSource類作為連線池初始化類

<!--連線池設定-->
    <bean id="dataSource" class="com.zaxxer.hikari.HikariDataSource" destroy-method="close"> 
        <property name="poolName" value="${hikari.poolName}" />
        <property name="autoCommit" value="${hikari.autoCommit}" />
        
        <property name="driverClassName" value="${hikari.driverClassName}"></property>
        <property name="jdbcUrl" value="${hikari.jdbcUrl}" />
        <property name="username" value="${hikari.username}" />
        <property name="password" value="${hikari.password}" />
        
        <property name="maximumPoolSize" value="${hikari.maximumPoolSize}" />
        <property name="minimumIdle" value="${hikari.minimumIdle}" />
        <property name="connectionTimeout" value="${hikari.connectionTimeout}" />
        <property name="idleTimeout" value="${hikari.idleTimeout}" />
        <property name="maxLifetime" value="${hikari.maxLifetime}" />
        <property name="connectionTestQuery" value="${hikari.connectionTestQuery}" /> 
    </bean>

在springboot中如何初始化HikariCP

在application.properties組態檔中設定

spring.datasource.type=com.zaxxer.hikari.HikariDataSource

其他引數與springboot正常連線設定相同,對應引數值參考上面的spring連線池設定引數