// SQLite 錯誤參考

SQLITE_BUSY:資料庫已鎖定

另一個連線持有 SQLite 需要的鎖定,通常是另一個處理序中的寫入者。設定忙碌逾時、讓寫入交易保持簡短,或改用 WAL 模式。

結果代碼
SQLITE_BUSY
名稱
5
類別
主要結果代碼
錯誤訊息
database is locked

它的意義

SQLite 每個資料庫檔案一次只允許一個寫入者。當某個連線需要另一個連線(在同一個或另一個處理序中)持有的鎖時,呼叫就會失敗,並出現 SQLITE_BUSY 以及訊息 database is locked,除非設定了 busy handler——那種情況下 SQLite 會先重試,最長重試到逾時。

預設情況下沒有 busy handler,所以會立即失敗。在 rollback-journal 模式下,讀取會阻擋寫入提交,寫入提交時也會阻擋新的讀取;WAL 模式則讓讀取與單一寫入同時進行。

常見原因

  • 兩個處理程序或執行緒同時寫入相同資料庫,且未設定忙碌逾時(busy timeout)。
  • 長時間的寫入交易(或 BEGIN 從未提交的交易)會握著鎖,讓其他人只能等。
  • 讀取交易開始於 BEGIN DEFERRED 會嘗試在另一個連線正在寫入時升級為寫入;在 WAL 模式下這會傳回 SQLITE_BUSY_SNAPSHOT 等待也無濟於事。
  • 你自己程式裡開著的資料指標或未完成的陳述式,會讓讀取交易一直保持開啟。
  • 資料庫檔案位於鎖定機制不可靠的網路檔案系統上。

如何修正

  1. 設定忙碌逾時,讓 SQLite 不會立即失敗,而是先等待並重試。大多數語言繫結都提供這項設定(Python 的 sqlite3 預設等待 5 秒;若要調高,可使用 sqlite3.connect(path, timeout=30)。在 SQL 中:

    PRAGMA busy_timeout = 5000;  -- milliseconds
  2. 把資料庫切換成預寫式記錄,讀取就不再封鎖寫入,寫入也不會封鎖讀取。

    PRAGMA journal_mode = WAL;
  3. 寫入交易請用 BEGIN IMMEDIATE,它會預先取得寫入鎖。忙碌的連線接著就會在 BEGIN (逾時就是在這裡套用),而不是半途失敗。

    BEGIN IMMEDIATE;
    UPDATE counters SET n = n + 1 WHERE name = 'visits';
    COMMIT;
  4. 保持交易簡短、儘早提交,並完成或重設每個陳述式(關閉游標),不讓任何連線持有鎖超過所需的時間。

  5. 把資料庫放在本機磁碟上,而不是網路共用資料夾。

安全地重現問題

對同一個暫存資料庫檔案使用兩個獨立的連線。

-- Connection 1 (for example the sqlite3 shell):
BEGIN IMMEDIATE;
INSERT INTO t VALUES (1);
-- Connection 2, same file, no busy timeout:
INSERT INTO t VALUES (2);   -- Runtime error: database is locked (5)

問題

SQLITE_BUSY 和 SQLITE_LOCKED 之間有什麼差別?

SQLITE_BUSY 表示另一個資料庫連線(通常在另一個處理程序中)持有衝突的鎖定。 SQLITE_LOCKED 表示衝突發生在你自己的連線內,或是在共用快取的連線之間,例如某個陳述式還在讀取資料表時就把表刪掉。

WAL 模式能解決「database is locked」錯誤嗎?

它消除了大多數讀寫衝突,但同一時間仍只有一個寫入者,因此並行寫入時仍需要忙碌逾時設定。

相關錯誤

更多主要結果碼錯誤

程式碼和訊息文字來自 SQLite 結果代碼與錯誤碼文件。瀏覽完整的 SQLite 錯誤清單 或 搜尋每個資料庫錯誤.

// 錯誤更少,修復更快

在 SQLly 裡操作 SQLite

適用於 macOS、Windows 和 Linux 的原生 SQL 客戶端,具備結構描述感知的 IntelliSense、高風險陳述式防護與清楚的錯誤訊息,適用於 SQLite 和你使用的其他資料庫。