できない.dev

SQLite で「database is locked」が出て書き込めない

database is locked は、開いたままの接続をコミットして閉じ、待ち時間と WAL モードを設定すれば直る。
SQLite は同時に 1 つの接続しか書き込めず、待ち時間を過ぎるとこのエラーになる。

公開: 更新:

症状できない
python bad_uncommitted.py
con1.in_transaction = True
sqlite3.OperationalError: database is locked(1.0 秒待って失敗)

2026-10-25 に python:3.12(Python 3.12.15 / Git 2.47.3) で実際に打って取った出力。検証環境の詳細

要約

2 つ目の接続から書き込もうとすると、しばらく待たされた後に失敗する。

sqlite3.OperationalError: database is locked

SQLite は同時に 1 つの書き込みしか受け付けない。
公式ドキュメントの SQLITE_BUSY の説明のとおり、別の接続が書き込みトランザクションの途中なら、後から来た接続はそれが終わるまで待つ必要がある。
待ち時間(busy timeout)を過ぎると、この database is locked が返る。
Python の sqlite3 では connect() の timeout が待ち時間で、既定は 5 秒だ。

実行例

Python 3.12.15 の標準 sqlite3 で試すと、コミットしていない接続があるとき 2 つ目の接続は待ち時間の 1 秒を過ぎて database is locked で失敗する。
with ブロックで書き込めば、両方の行が入る。
相手の書き込みに 1 秒かかる場面では、timeout=0.3 だと 0.3 秒で諦めるが、timeout=5.0 なら約 1 秒待って書き込める。
読み取り中の接続があるとき、ロールバックジャーナルでは書き込み側のコミットが失敗し、WAL モードでは成功する。

$ python bad_uncommitted.py
con1.in_transaction = True
sqlite3.OperationalError: database is locked(1.0 秒待って失敗)
$ python solve_with.py
con1.in_transaction = False
[(1,), (2,)]
$ python timeout_demo.py
timeout=0.3: database is locked(0.3 秒で諦めた)
timeout=5.0: 書き込めた(1.0 秒待った)
$ python journal_demo.py DELETE
journal_mode = delete
writer.commit(): database is locked
$ python journal_demo.py WAL
journal_mode = wal
writer.commit(): 成功

— 2026-10-25 時点の出力

検証環境Python 3.12.15 / Git 2.47.3 / 2026-10-25 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.15
  • Git 2.47.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. トランザクションを短くし、失敗したら戻す

接続を with で使うと、ブロックを抜けるときに成功なら commit()、例外なら rollback() が呼ばれる。

import sqlite3
 
con = sqlite3.connect("app.db")
con.execute("CREATE TABLE IF NOT EXISTS t(x)")
with con:
    con.execute("INSERT INTO t VALUES (?)", (1,))
con.close()

with は接続を閉じないので、使い終わったら close() する。
書き込みの前に重い処理を挟まず、トランザクションを開いている時間を短くする。

2. 待ち時間を延ばす

con = sqlite3.connect("app.db", timeout=10.0)

Python 以外のクライアントでは、SQL で設定できる。

PRAGMA busy_timeout = 10000;  -- ミリ秒

待ち時間は接続ごとの設定なので、すべての接続で設定する。

3. WAL モードにする

PRAGMA journal_mode=WAL;

WAL モードでは、書き込み中でも他の接続は読み取れる。
一度設定するとデータベースファイルに記録され、以降の接続にも引き継がれる。
書き込みは引き続き 1 つずつなので、手順 1 と 2 は WAL でも必要になる。
ファイルの横にできる -wal はデータベースの一部なので、コピーや移動のときは本体と一緒に扱う(-shm は共有メモリ用の索引ファイル)。

4. ネットワーク上に置かない

NFS や SMB の共有フォルダに置いたデータベースを複数のマシンから書き込む構成は避け、ローカルのディスクに置く。
複数のサーバーから同時に書き込む用途には、サーバー型のデータベースを検討する。

よくある原因

  1. コミットしていない接続がある。
    Python の sqlite3 は既定で INSERT / UPDATE / DELETE の前に暗黙にトランザクションを開く。
    commit() を呼ぶまで、他の接続は書き込めない。
  2. 失敗した接続がロックを持ち続けている。
    書き込みに失敗した接続は、rollback() するまでトランザクションの中にいる(con.in_transaction が True のまま)。
    そのまま SELECT を実行すると読み取りのロックを持ち続け、今度は相手側の commit() が database is locked で失敗する。
  3. 待ち時間が短い。
    timeout=0.5 なら 0.5 秒で諦めるので、相手が 1 秒で終わる処理でも失敗する。
  4. ロールバックジャーナルのまま使っている。
    既定のジャーナルでは、読み取り中の接続があると書き込み側がコミットできない。
  5. データベースファイルをネットワーク上に置いている。
    SQLite の書き込みはファイルロックに頼っている。
    公式ドキュメントは、ネットワークファイルシステムではこのロックが正しく動かない例があると注意している。
    WAL モードも同じホストのプロセスで共有メモリを使う仕組みなので、ネットワークファイルシステムでは使えない。