// Referencia de errores de SQLite

SQLITE_BUSY: La base de datos está bloqueada

Otra conexión mantiene un bloqueo que SQLite necesita, usualmente un escritor en otro proceso. Define un tiempo de espera cuando la base esté ocupada, mantén cortas las transacciones de escritura o cambia al modo WAL.

Código de resultado
SQLITE_BUSY
Nombre
5
Categoría
Códigos de resultado primarios
Mensaje de error
database is locked

Qué significa

SQLite permite un solo escritor a la vez por archivo de base de datos. Cuando una conexión necesita un bloqueo que otra conexión (en el mismo o en otro proceso) ya tiene, la llamada falla con SQLITE_BUSY y el mensaje database is locked, a menos que haya un manejador de ocupación configurado, en cuyo caso SQLite reintenta primero hasta agotar el tiempo de espera.

Por defecto no hay ningún manejador de busy, así que el fallo es inmediato. En el modo de diario de reversión (rollback-journal) los lectores también impiden que un escritor haga commit, y un escritor bloquea a los nuevos lectores mientras hace commit; el modo WAL permite que los lectores y un escritor trabajen a la vez.

Causas comunes

  • Dos procesos o hilos escriben a la vez en la misma base de datos, sin un busy timeout configurado.
  • Una transacción de escritura larga (o un BEGIN que nunca se confirmó) mantiene el bloqueo mientras otros esperan.
  • Una transacción de lectura iniciada con BEGIN DEFERRED intenta pasar a escritura mientras otra conexión está escribiendo; en modo WAL esto devuelve SQLITE_BUSY_SNAPSHOT y esperar no ayudará.
  • Un cursor abierto o una instrucción sin terminar en tu propio programa mantiene abierta una transacción de lectura.
  • El archivo de la base de datos está en un sistema de archivos de red cuyo bloqueo no funciona de manera confiable.

Cómo solucionarlo

  1. Configura un busy timeout para que SQLite espere y reintente en lugar de fallar de inmediato. La mayoría de los bindings lo exponen (Python sqlite3 espera 5 segundos por defecto; súbelo con sqlite3.connect(path, timeout=30)). En SQL:

    PRAGMA busy_timeout = 5000;  -- milliseconds
  2. Cambia la base de datos a registro de escritura anticipada, de modo que los lectores ya no bloqueen al escritor ni este a los lectores.

    PRAGMA journal_mode = WAL;
  3. Inicia transacciones de escritura con BEGIN IMMEDIATE, que toma el bloqueo de escritura de antemano. Una conexión ocupada espera entonces en BEGIN (donde se aplica el tiempo de espera) en lugar de fallar a mitad del proceso.

    BEGIN IMMEDIATE;
    UPDATE counters SET n = n + 1 WHERE name = 'visits';
    COMMIT;
  4. Mantén cortas las transacciones, confirma rápidamente y termina o reinicia cada instrucción (cierra los cursores) para que ninguna conexión mantenga un bloqueo más tiempo del necesario.

  5. Mantén la base de datos en un disco local, no en un recurso compartido de red.

Reprodúcelo de forma segura

Usa dos conexiones separadas al mismo archivo de base de datos temporal.

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

Preguntas

¿Cuál es la diferencia entre SQLITE_BUSY y SQLITE_LOCKED?

SQLITE_BUSY significa que otra conexión a la base de datos, normalmente en otro proceso, tiene un bloqueo en conflicto. SQLITE_LOCKED significa que el conflicto está dentro de tu propia conexión o entre conexiones que comparten un caché, por ejemplo, eliminar una tabla mientras una instrucción aún la está leyendo.

¿El modo WAL elimina el error database is locked?

Elimina la mayoría de los conflictos lector-escritor, pero todavía solo hay un escritor a la vez, por lo que los escritores concurrentes aún necesitan un tiempo de espera por ocupación.

Errores relacionados

Más errores de códigos de resultado principales

El código y el texto del mensaje son de Documentación de los códigos de resultado y de error de SQLite. Explora la lista completa de Lista de errores de SQLite o buscar cada error de base de datos.

// menos errores, correcciones más rápidas

Trabajar con SQLite en SQLly

Un cliente SQL nativo para macOS, Windows y Linux con IntelliSense que conoce el esquema, protecciones para las instrucciones de riesgo y mensajes de error claros, para SQLite y las demás bases de datos que uses.