依連線池狀態診斷取得連線逾時,以 H2 範例重現耗盡、釋放與再次取得連線。
適用:JDK 25 編譯與執行;HikariCP 範例的第三方版本以文內依賴清單為準,使用本地 H2 模擬連線池。
遇到 Connection is not available, request timed out after 30000ms,表示呼叫端在等待期限內沒有從 HikariCP 取得可用連線。先觀察連線的使用情況,再判斷要修程式、查詢或設定。
錯誤代表什麼
常見訊息:
java.sql.SQLTransientConnectionException:
HikariPool-1 - Connection is not available, request timed out after 30000ms.connectionTimeout 是呼叫 getConnection() 時,等待從連線池取得連線的最長時間,單位為毫秒。它不是 SQL 查詢的執行逾時。 查詢執行很久,可能因為長時間佔用連線,間接讓其他請求無法取得連線。
HikariCP 的預設值為 30000 ms,最低接受值為 250 ms。提高等待時間只是讓請求等得更久,不能修復連線未歸還、慢查詢或資料庫不可用等根因。
建議的診斷順序
- 觀察連線池。 檢查使用中與閒置的連線數,以及等待連線的執行緒數。若全部連線長期使用中,再查是哪個工作佔用。
- 確認生命週期。 JDBC 連線、Statement 與 ResultSet 使用 try-with-resources,交易完成後應歸還連線。不要在取得連線後執行耗時的外部服務呼叫。
- 查 SQL 與交易。 看慢查詢、鎖等待、未完成交易與一次讀取過量資料。
- 檢查資料庫與網路。 確認資料庫可連線、連線額度、認證與網路是否正常;同時看連線建立失敗的日誌。
- 再調整容量與等待。 根據併發需求與資料庫容量評估
maximumPoolSize;等待時間應符合請求可接受的時間。增加連線數也可能讓資料庫負擔更重。
leakDetectionThreshold 可以協助記錄連線被借出過久的位置,但它不會自動回收該連線,日誌也不必然代表真正的洩漏。
設定範例
Spring Boot 使用 HikariCP 的設定位置如下;縮排用空白,所有時間值均為毫秒。這是設定位置示例,應依實際環境量測後調整。
spring:
datasource:
hikari:
minimum-idle: 2
maximum-pool-size: 10
idle-timeout: 120000
connection-timeout: 30000下面的 Java 練習刻意使用 1 條連線與 300 ms 等待,快速重現問題;與上面的應用設定分開使用。
驗證環境與依賴
- OpenJDK 25.0.4.1;java 與 javac 均為 25,編譯產物 class major version 為 69。
- HikariCP 7.0.2、H2 2.4.240、SLF4J API 2.0.17。
- H2 使用記憶體資料庫,無需啟動外部資料庫。
Maven dependency 座標:
<dependencies>
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>7.0.2</version>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>2.4.240</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>2.0.17</version>
</dependency>
</dependencies>若直接用 javac,把以上三個依賴的 JAR 放在 lib/。SLF4J API 沒有 provider 時會輸出提示,但不影響本範例的 JDBC 行為。
若整合進 Maven 專案,編譯器也要使用 JDK 25;Spring Boot 專案設定 java.version=25,一般 Maven 專案則設定 maven.compiler.release=25。上述區塊僅列出依賴座標,本文實測使用下方的 javac/java 指令。
完整重現範例
存為 PoolTimeoutDemo.java:
import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLTransientConnectionException;
import java.sql.Statement;
public class PoolTimeoutDemo {
public static void main(String[] args) throws Exception {
HikariConfig config = new HikariConfig();
config.setPoolName("note-demo");
config.setJdbcUrl("jdbc:h2:mem:pool_demo");
config.setMaximumPoolSize(1);
config.setMinimumIdle(1);
config.setConnectionTimeout(300);
config.setValidationTimeout(250);
try (HikariDataSource pool = new HikariDataSource(config)) {
try (Connection held = pool.getConnection()) {
long started = System.nanoTime();
try (Connection unexpected = pool.getConnection()) {
throw new AssertionError("應該因為池已耗盡而逾時");
} catch (SQLTransientConnectionException expected) {
long waitedMillis = (System.nanoTime() - started) / 1_000_000;
if (waitedMillis < 250) {
throw new AssertionError("等待不足 250 ms:" + waitedMillis);
}
System.out.println("連線被佔用:第二次取得連線逾時");
}
}
// held.close() 已將連線歸還池。
try (Connection recovered = pool.getConnection();
Statement statement = recovered.createStatement();
ResultSet result = statement.executeQuery("SELECT 1")) {
if (!result.next() || result.getInt(1) != 1) {
throw new AssertionError("連線釋放後應可執行查詢");
}
System.out.println("連線已釋放:再次取得連線並查詢成功");
}
}
}
}macOS/Linux 執行:
javac -encoding UTF-8 -cp "lib/*" PoolTimeoutDemo.java
java -cp ".:lib/*" PoolTimeoutDemoWindows 的 classpath 分隔符改用 ;,執行時使用 java -cp ".;lib/*" PoolTimeoutDemo。
預期標準輸出:
連線被佔用:第二次取得連線逾時
連線已釋放:再次取得連線並查詢成功第一個 try 區塊借走唯一的連線;第二次取得會等待到期後丟出例外。範例另外確認等待至少 250 ms,避免把立即失敗誤當成等待逾時;這個下限只用於驗證行為,並非效能指標。第一個區塊結束後,連線歸還池,下一次取得就能執行查詢。
限制與重點回顧
這個本機練習驗證的是「池內無可用連線」的機制,沒有模擬網路故障、真實服務負載或資料庫鎖等待。H2 查詢成功也不代表正式環境的容量設定適當。
遇到逾時時先找出連線為何無法使用。確認根因後,再評估池大小與等待設定;不要只把等待時間改長。
- HikariCP 7.0.2:Configuration
- H2:Database URL 與 Embedded Mode
- 原始問題參考: Stack Overflow:HikariPool connection timeout 。本文已補上獨立重現步驟與限制。
修訂確認
原有完整範例保留;本文是可控的學習情境,實際系統還需依資料庫延遲與併發負載調整。查核不代表任何引數能直接適用所有 production 服務。
系列導覽
00 環境 · 01 第一支程式 · 02 型別 · 03 變數 · 04 物件導向 · 多型範例
冒險者留言
comments powered by Disqus