解決 Hibernate SQLGrammarException: could not execute query 錯誤

Hibernate 執行查詢拋出 SQLGrammarException 的常見原因與解決

在 SSH（Struts + Spring + Hibernate）專案開發中，開發者常會遇到 org.hibernate.exception.SQLGrammarException: could not execute query 這個異常。乍看之下似乎是 SQL 語法錯誤，但經過仔細排查，往往是由於 API 使用不當導致。

問題現場

專案原本使用 HQL（Hibernate Query Language）進行查詢，正確的做法是呼叫 Session.createQuery(hqlString)。然而，不小心將其寫成了 Session.createSQLQuery(sqlString)，導致 Hibernate 嘗試以原生 SQL 的方式解析 HQL 語句，自然會引發語法錯誤，無法執行查詢。

錯誤代碼示例

// 錯誤寫法：將 HQL 當成原生 SQL 執行
Query query = session.createSQLQuery("from User where name = ?");

正確寫法

// 正確寫法：使用 createQuery 執行 HQL
Query query = session.createQuery("from User where name = ?");

核心差異

• createQuery()：用於執行 HQL（或 JPQL），操作的是實體類與屬性，與資料庫表結構解耦。
• createSQLQuery()：用於執行原生 SQL，直接操作資料庫表與欄位，需自行處理結果映射。

避坑指南

1. 確認查詢語句是 HQL 還是原生 SQL，選擇對應的 API。
2. 若確實需要原生 SQL，請使用 createSQLQuery() 並搭配 addEntity() 或 setResultTransformer() 進行結果映射。
3. 開啟 Hibernate SQL 日誌（hibernate.show_sql=true）可幫助快速定位實際執行的 SQL。

這個錯誤雖然簡單，但極易在重構或複製代碼時引入。養成區分 HQL 與 SQL 的習慣，能有效避免此類低級錯誤。