"Database disk image is malformed"

Una base de datos SQLite es un único archivo cortado en páginas de tamaño fijo — una potencia de dos entre 512 y 65536 bytes, almacenada como un valor de 16 bits en el desplazamiento 16 de la cabecera (el valor en disco 1 es la forma que tiene la especificación de representar 65536). Todo archivo empieza con la cadena mágica de 16 bytes SQLite format 3\0, seguida de una cabecera de 100 bytes que registra el tamaño de página, la codificación de texto en el desplazamiento 56 (1 = UTF-8, 2 = UTF-16le, 3 = UTF-16be), el número de páginas declarado en el desplazamiento 28 y la lista de libres (freelist). Si el tamaño de página se lee mal, cada página posterior a la primera cae en el desplazamiento equivocado — y esa es una de las formas en que un archivo queda "malformed" sin que se toque una sola fila.

Dentro, los datos viven en b-trees. Cada página empieza con un byte de tipo: 0x0d para una hoja de tabla (que contiene las filas reales), 0x05 para una interior de tabla (que solo contiene punteros a páginas hijas) y 0x0a/0x02 para los equivalentes de índice. La página 1 es especial — su cabecera de b-tree va después de la cabecera de base de datos de 100 bytes — y es la raíz de sqlite_master, la tabla de esquema cuyas filas son (type, name, tbl_name, rootpage, sql). Para leer una de tus tablas, SQLite busca ahí su rootpage, luego desciende por las páginas interiores hasta las hojas, leyendo de cada celda la longitud de carga (varint), el rowid (varint) y el cuerpo del registro.

Como una consulta recorre este árbol, un solo enlace roto envenena todo lo que hay por debajo. Una página interior puesta a ceros, un puntero de celda que apunta más allá del final de la página, un puntero al extremo derecho que forma un bucle, o una cabecera de registro cuyos tipos serie no cuadran — cualquiera de estos hace que SQLite lance "database disk image is malformed" en cuanto pisa el daño. Las filas de las páginas hoja sanas están intactas; SQLite simplemente no puede alcanzarlas a través de un índice roto. PRAGMA integrity_check informa de esta misma clase de fallo.

La solución imita lo que hace el propio comando .recover del shell de SQLite, pero se ejecuta enteramente en el navegador. Primero la herramienta lee sqlite_master desde la página 1 para conocer el nombre de cada tabla, sus columnas (extraídas del SQL de su CREATE TABLE) y su rootpage, y luego recorre cada b-tree desde esa raíz — la vía rápida y exacta cuando los punteros están intactos. Cuando un recorrido topa con una página que falta o es inválida, degrada a "incompleto" en vez de fallar, conservando todas las filas que reunió hasta la ruptura.

Después llega la parte que supera a un simple reintento de apertura: un barrido sin punteros. El escáner ignora todos los punteros y trata cada página hoja de tabla (tipo 0x0d) del archivo como una bolsa de registros, decodificando cada celda directamente de sus bytes — la longitud de la cabecera (varint), el array de tipos serie y luego cada valor (el tipo serie 0 es NULL, 8/9 son los literales 0 y 1, 7 es un float64, y los códigos pares/impares por encima de 12 son BLOB/TEXT). Las cadenas de desbordamiento (overflow) de los valores grandes se siguen de página en página. Así es exactamente como sobreviven las filas a una página interior puesta a ceros, a una página en la freelist o a una tabla eliminada: la hoja sigue conteniendo los datos aunque ya nada apunte a ella. Las filas cuyo número de columnas coincide de forma inequívoca con una tabla conocida se reinsertan en ella; las que de verdad no se pueden atribuir se escriben en una tabla lost_and_found con columnas pgno, cellidx, nfield, rowid y c0…cN, de modo que no se descarta nada decodificable.

Por último la herramienta construye una base de datos nueva con sqlite3.wasm (cargado desde el mismo origen en /engines/sqlite/), emitiendo un CREATE TABLE permisivo para cada tabla — se conservan los nombres originales de las columnas y cualquier INTEGER PRIMARY KEY para que el alias del rowid se mantenga, pero sin restricciones NOT NULL/UNIQUE/CHECK/clave foránea que rechazarían una fila resucitada — y luego hace INSERT OR IGNORE de cada fila recuperada y exporta el resultado como un .db limpio. Si se aporta un archivo hermano -wal (registro de escritura anticipada), sus tramas confirmadas se superponen primero, de forma que la recuperación refleja la última transacción confirmada.

La recuperación alcanza lo que está presente; no puede inventar lo que el disco ya no guarda. Si el archivo quedó truncado — una copia o sincronización que se detuvo antes de tiempo, dejando un tamaño que no es un múltiplo exacto del tamaño de página — toda página posterior al corte ha desaparecido físicamente, y obtienes las filas que se escribieron por completo antes de él. Las celdas que están en páginas intactas pero cuya cabecera de registro es incoherente consigo misma (el clásico bit-rot) se descartan y se cuentan, en lugar de adivinarlas. Una base de datos cifrada (SQLCipher o la extensión SEE) no tiene magia en texto plano — su primera página es texto cifrado — así que sin la clave no hay nada que recorrer, y no se intenta la recuperación.

Dos advertencias de honestidad en las que el propio SQLite insiste. Las filas eliminadas pueden reaparecer: el escaneo sin punteros lee páginas de la freelist y sin compactar (vacuum), así que registros que creías desaparecidos pueden resurgir en el resultado. Y los valores recuperados reflejan las clases de almacenamiento en disco, no las afinidades de columna declaradas — el tipo aparente de una columna puede cambiar. La propia guía de SQLite es tajante: los datos extraídos de una base de datos corrupta son siempre sospechosos. Verifícalos contra una fuente fiable antes de confiar en ellos.

Todo esto se ejecuta en la pestaña de tu navegador — el escáner es TypeScript sin dependencias y el escritor es WASM, así que no hay ida y vuelta a un servidor. Eso importa cuando la base de datos es un gestor de contraseñas, un historial de chat, datos de salud o el almacén privado de una app: puedes abrir la pestaña Red y confirmar que nunca salen 0 bytes del archivo de tu equipo.