JDBC 處理 CLOB 大文本字段完整實戰指南

資料庫 CLOB（Character Large Object）用於存儲超過 VARCHAR 上限的大文本（XML、JSON、日誌、長文）。本文示範 JDBC 標準 API 寫入/讀取 CLOB 的正確姿勢，避免記憶體溢出與流未關閉問題。

一、寫入 CLOB（推薦：流式寫入）

String sql = "INSERT INTO doc(content) VALUES(?)";
try (Connection conn = ds.getConnection();
     PreparedStatement ps = conn.prepareStatement(sql)) {
     
    // 方式 1：JDBC 4.0+ 直接 setCharacterStream（推薦，無需建立 Clob 物件）
    try (Reader reader = new StringReader(largeText)) {
        ps.setCharacterStream(1, reader, largeText.length());
        ps.executeUpdate();
    }
    
    // 方式 2：建立 Clob 物件（舊版驅動兼容）
    // Clob clob = conn.createClob();
    // clob.setString(1, largeText);
    // ps.setClob(1, clob);
}

• setCharacterStream 避免一次性載入巨大字串到 JVM 堆，直接流式傳輸到資料庫。
• 若文本來源為檔案，改用 new FileReader(file) 即可零拷貝上傳。

二、讀取 CLOB（推薦：流式讀取）

String sql = "SELECT content FROM doc WHERE id=?";
try (Connection conn = ds.getConnection();
     PreparedStatement ps = conn.prepareStatement(sql);
     ResultSet rs = ps.executeQuery()) {
     
    ps.setLong(1, docId);
    if (rs.next()) {
        // 方式 1：getCharacterStream（推薦，流式處理）
        try (Reader reader = rs.getCharacterStream("content");
             StringWriter writer = new StringWriter()) {
            char[] buffer = new char[8192];
            int len;
            while ((len = reader.read(buffer)) != -1) {
                writer.write(buffer, 0, len);
            }
            String content = writer.toString();
            // 處理 content...
        }
        
        // 方式 2：getAsciiStream（僅適用 ASCII/ISO-8859-1，中文會亂碼）
        // InputStream is = rs.getAsciiStream("content");
        
        // 方式 3：getSubString（一次性載入，慎用於大 CLOB）
        // String content = rs.getClob("content").getSubString(1, (int) clob.length());
    }
}

三、CLOB vs BLOB 選型

四、主流資料庫 CLOB 類型映射

五、效能優化建議

1. 流式讀寫：嚴禁 getSubString(1, length) 或 clob.getAsciiStream() 全量載入記憶體。
2. 分塊處理：超大文本（>100MB）採用分塊寫入/讀取，配合資料庫 DBMS_LOB.WRITEAPPEND（Oracle）或分頁查詢。
3. 連線池預處理：複用 PreparedStatement 減少解析開銷。
4. 壓縮存儲：文本壓縮（GZIP）後存 BLOB，讀取時解壓，節省 70%+ 空間。

六、常見錯誤與排查

七、總結

• 寫入：ps.setCharacterStream(1, reader, length) 流式零拷貝。
• 讀取：rs.getCharacterStream("col") + 緩衝區循環讀取。
• 大文本優先考慮壓縮存 BLOB 或對象存儲（S3/MinIO），資料庫僅存元數據引用。