// справочник ошибок SQLite

SQLITE_BUSY: база данных заблокирована

Другое соединение удерживает блокировку, необходимую SQLite, обычно писатель в другом процессе. Установите таймаут при занятости, держите транзакции записи короткими или переключитесь в режим WAL.

Код результата
SQLITE_BUSY
Имя
5
Категория
Основные коды результатов
Сообщение об ошибке
database is locked

Что это значит

Одновременно писать в файл базы данных SQLite может только одно соединение. Когда соединению нужна блокировка, которую удерживает другое соединение (в том же или другом процессе), вызов завершается с ошибкой SQLITE_BUSY и сообщением database is locked, если не задан обработчик занятости; тогда SQLite сначала повторяет попытки до истечения таймаута.

По умолчанию обработчик занятости отсутствует, поэтому сбой происходит сразу. В режиме rollback-journal читатели, кроме того, не дают писателю зафиксировать транзакцию, а писатель во время фиксации блокирует новых читателей; режим WAL позволяет читателям и одному писателю работать одновременно.

Распространённые причины

  • Два процесса или потока одновременно записывают в одну и ту же базу данных, при этом таймаут занятости не установлен.
  • Долгая транзакция записи (или BEGIN которая никогда не была зафиксирована) удерживает блокировку, пока другие ожидают.
  • Транзакция на чтение, начатая с BEGIN DEFERRED пытается перейти к записи, пока другое соединение уже пишет; в режиме WAL это возвращает SQLITE_BUSY_SNAPSHOT и ожидание не поможет.
  • Открытый курсор или незавершённый оператор в вашей собственной программе держит транзакцию чтения открытой.
  • Файл базы данных находится на сетевой файловой системе, блокировки на которой срабатывают ненадежно.

Как исправить

  1. Установите тайм-аут занятости, чтобы SQLite ждал и повторял попытку, а не падал сразу. Большинство привязок его предоставляют (в Python sqlite3 ждёт 5 секунд по умолчанию; увеличьте его с помощью sqlite3.connect(path, timeout=30)). В SQL:

    PRAGMA busy_timeout = 5000;  -- milliseconds
  2. Переключите базу данных на упреждающее журналирование (write-ahead logging), чтобы читатели больше не блокировали писателя, а писатель — читателей.

    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 или поиск по всем ошибкам баз данных.

// меньше ошибок, быстрее исправления

Работа с SQLite в SQLly

Нативный SQL-клиент для macOS, Windows и Linux с IntelliSense, который знает вашу схему, предохранителями для рискованных запросов и понятными сообщениями об ошибках — для SQLite и других баз данных, которые вы используете.