Hibernate 連接 SQL Server 常見問題與 jTDS 驅動解決方案

問題現象

專案原使用 Microsoft 官方 JDBC 驅動（com.microsoft.jdbc.base.BaseDatabaseMetaData），單獨測試連線正常，但整合 Hibernate 後拋出：

java.lang.AbstractMethodError: com.microsoft.jdbc.base.BaseDatabaseMetaData.getJDBCMajorVersion()I
// 或
java.lang.AbstractMethodError: com.microsoft.jdbc.base.BaseDatabaseMetaData.supportsGetGeneratedKeys()Z

根因：Microsoft 早期 JDBC 驅動未完整實作 JDBC 3.0/4.0 介面，Hibernate 內部呼叫 DatabaseMetaData 進階方法時觸發 AbstractMethodError。

解決方案：改用 jTDS 驅動

jTDS 是開源、輕量、完整實作 JDBC 4.0 的 SQL Server / Sybase 驅動，廣泛用於 Hibernate、Spring、Tomcat 等生態系。

Maven 依賴

<dependency>
    <groupId>net.sourceforge.jtds</groupId>
    <artifactId>jtds</artifactId>
    <version>1.3.1</version> <!-- JDK 8+ 使用 1.3.1；JDK 6/7 請用 1.2.x -->
</dependency>

Hibernate 設定檔（hibernate.cfg.xml 或 application.yml）

<property name="connection.driver_class">net.sourceforge.jtds.jdbc.Driver</property>
<property name="connection.url">jdbc:jtds:sqlserver://<host>:<port>/<dbName>;instance=<instanceName>;charset=utf8</property>
<property name="connection.username">your_user</property>
<property name="connection.password">your_pwd</property>
<property name="dialect">org.hibernate.dialect.SQLServerDialect</property> <!-- 依版本調整：SQLServer2012Dialect 等 -->

關鍵連線參數說明

版本相容性對照表

常見坑點排查

1. 類別路徑衝突：專案內同時存在 sqljdbc.jar 與 jtds.jar，類別載入器可能優先載入舊驅動 → 徹底移除 Microsoft 驅動。
2. Tomcat 共用類別載入器：將 jtds.jar 放入 $CATALINA_HOME/lib，避免 Webapp 類別載入器隔離導致重複載入。
3. 命名執行個體連線失敗：確認 SQL Server Browser 服務啟動，防火牆開放 UDP 1434；或在連線字串明確指定 port 略過 Browser。
4. 大字段（MAX 型別）讀取截斷：設定 lobBuffer=524288（512KB）或更大。

遷移驗證清單

• [ ] 所有實體映射正常載入（SessionFactory 建立無誤）。
• [ ] CRUD 操作、樂觀鎖、批次處理、Stored Procedure 呼叫測試通過。
• [ ] 連線池（HikariCP / DBCP2）與 jTDS 相容性驗證（validationQuery=SELECT 1）。
• [ ] 效能基準測試：對比舊驅動，確認無嚴重回歸。