// Referência de erro do SQLite

SQLITE_BUSY: o banco de dados está bloqueado

Outra conexão tem um bloqueio de que o SQLite precisa, geralmente um escritor em outro processo. Defina um busy timeout, mantenha as transações de escrita curtas ou mude para o modo WAL.

Código de resultado
SQLITE_BUSY
Nome
5
Categoria
Códigos de resultado primários
Mensagem de erro
database is locked

O que significa

O SQLite permite um escritor por vez por arquivo de banco de dados. Quando uma conexão precisa de um bloqueio que outra conexão (no mesmo ou em outro processo) possui, a chamada falha com SQLITE_BUSY e a mensagem database is locked, a menos que haja um manipulador de ocupação configurado, caso em que o SQLite tenta de novo por até o tempo limite primeiro.

Por padrão, não há um manipulador de ocupação, então a falha é imediata. No modo rollback-journal, os leitores também impedem que um escritor faça o commit, e um escritor bloqueia novos leitores enquanto faz o commit; o modo WAL permite que leitores e um escritor trabalhem ao mesmo tempo.

Causas comuns

  • Dois processos ou threads escrevem no mesmo banco de dados ao mesmo tempo, sem tempo limite de espera definido.
  • Uma longa transação de escrita (ou uma BEGIN aquilo que nunca foi confirmado) mantém o bloqueio enquanto outros esperam.
  • Uma transação de leitura iniciada com BEGIN DEFERRED tenta atualizar para uma escrita enquanto outra conexão está escrevendo; no modo WAL isso retorna SQLITE_BUSY_SNAPSHOT e esperar não ajudará.
  • Um cursor aberto ou uma instrução não finalizada no seu próprio programa mantém uma transação de leitura aberta.
  • O arquivo de banco de dados está em um sistema de arquivos de rede cujo bloqueio não funciona de maneira confiável.

Como corrigir

  1. Defina um busy timeout para que o SQLite aguarde e tente novamente em vez de falhar imediatamente. A maioria dos bindings o expõe (Python's sqlite3 espera 5 segundos por padrão; aumente com sqlite3.connect(path, timeout=30)). Em SQL:

    PRAGMA busy_timeout = 5000;  -- milliseconds
  2. Mude o banco de dados para write-ahead logging, para que os leitores não bloqueiem mais o escritor e o escritor não bloqueie os leitores.

    PRAGMA journal_mode = WAL;
  3. Inicie transações de escrita com BEGIN IMMEDIATE, que pega o bloqueio de escrita de antemão. Uma conexão ocupada então espera em BEGIN (onde o tempo limite se aplica) em vez de falhar no meio do processo.

    BEGIN IMMEDIATE;
    UPDATE counters SET n = n + 1 WHERE name = 'visits';
    COMMIT;
  4. Mantenha as transações curtas, faça o commit rapidamente e finalize ou redefina cada instrução (feche os cursores) para que nenhuma conexão segure um bloqueio por mais tempo do que o necessário.

  5. Mantenha o banco de dados em um disco local, não em um compartilhamento de rede.

Reproduza com segurança

Use duas conexões separadas para o mesmo arquivo de banco de dados temporário.

-- 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)

Perguntas

Qual é a diferença entre SQLITE_BUSY e SQLITE_LOCKED?

SQLITE_BUSY significa que outra conexão com o banco de dados, geralmente em outro processo, mantém um bloqueio conflitante. SQLITE_LOCKED significa que o conflito está dentro da sua própria conexão ou entre conexões que compartilham um cache, por exemplo, excluindo uma tabela enquanto uma instrução ainda está lendo-a.

O modo WAL faz o erro database is locked desaparecer?

Ele remove a maioria dos conflitos entre leitores e escritores, mas ainda há apenas um escritor por vez, então escritores simultâneos ainda precisam de um busy timeout.

Erros relacionados

Mais erros de códigos de resultado primário

O código e o texto da mensagem são de Documentação de códigos de resultado e erro do SQLite. Veja toda a Lista de erros do SQLite ou pesquise todos os erros do banco de dados.

// menos erros, correções mais rápidas

Trabalhe com SQLite no SQLly

Um cliente SQL nativo para macOS, Windows e Linux com IntelliSense que conhece o esquema, proteções para instruções arriscadas e mensagens de erro claras, para o SQLite e os outros bancos de dados que você usa.