Java 連接遠端 Oracle 資料庫常見錯誤排查清單

錯誤現象

JDBC 連接遠端 Oracle 失敗，控制台拋出 SQLException 或連線逾時。

標準排查步驟

1. 捕獲完整堆疊追蹤：務必在 catch (SQLException e) { e.printStackTrace(); } 中輸出完整錯誤，包含 Error Code、SQLState、訊息。
2. 驗證連線字串：

   // 傳統 Thin Driver 格式
   jdbc:oracle:thin:@//host:port/service_name
   // 或 SID 格式
   jdbc:oracle:thin:@host:port:SID
   

   確認 host、port（預設 1521）、service_name/SID 正確。
3. 確認帳號密碼：用 SQL*Plus 或 SQL Developer 以相同帳號密碼測試能否登入。
4. 檢查驅動程式：
   • Maven 依賴：com.oracle.database.jdbc:ojdbc8:21.1.0.0（或對應版本）。
   • 驅動版本需與 JDK、Oracle 版本相容（Oracle 19c 建議 ojdbc10/11）。
5. 網路與防火牆：
   • Server 端 listener.ora 監聽正確 IP/埠。
   • 客戶端能 telnet host 1521 通聯。
   • 雲端資料庫（AWS RDS, Oracle Cloud）需設定 Security Group / Ingress 規則開放來源 IP。
6. Oracle 伺服器端設定：
   • 資料庫狀態 OPEN。
   • 監聽器狀態 READY（lsnrctl status）。
   • 若用 PDB，確認連線字串使用正確 Service Name。
7. 常見錯誤代碼對照：

   Error Code	常見原因
   ORA-12541	無監聽器（Listener 未啟動或埠錯誤）
   ORA-12514	Listener 不認得服務名（SID/Service Name 錯誤）
   ORA-01017	帳號/密碼錯誤
   ORA-28000	帳號被鎖定
   ORA-12170	連線逾時（防火牆/網路不通）

最小可行性測試程式

import java.sql.*;

public class TestOracleConn {
    public static void main(String[] args) {
        String url = "jdbc:oracle:thin:@//192.168.1.100:1521/ORCL";
        String user = "scott";
        String pwd = "tiger";
        try (Connection conn = DriverManager.getConnection(url, user, pwd)) {
            System.out.println("連線成功！");
            DatabaseMetaData meta = conn.getMetaData();
            System.out.println("Driver: " + meta.getDriverName());
            System.out.println("DB Version: " + meta.getDatabaseProductVersion());
        } catch (SQLException e) {
            e.printStackTrace(); // 關鍵：看完整堆疊
        }
    }
}