La capa VFS: el punto de extensión

Todo lo que has visto en las dos lecciones anteriores converge aquí. Un motor de ocho capas cuya única superficie de contacto con el exterior es la de abajo; un entorno que no tiene nada de lo que esa capa presupone; y entre ambos, una interfaz que su autor definió hace décadas con un objetivo modesto —que el mismo código corriera en Unix y en Windows— y que resultó ser lo bastante estrecha y lo bastante honesta como para admitir un sistema operativo que nadie había concebido. Esta lección disecciona esa interfaz operación por operación, porque las decisiones de la lección 4 y los límites de concurrencia que arrastrarás en producción no son otra cosa que consecuencias de lo que este contrato exige y de lo que el navegador puede prometer.

Dónde está la frontera

El pager es el último componente del motor que razona en términos de base de datos. Por debajo de él ya no hay tablas, ni filas, ni índices, ni transacciones: hay un fichero, hay desplazamientos, hay longitudes y hay un puñado de estados de bloqueo. La capa que atiende esas peticiones se llama VFS, por sistema de ficheros virtual, y es deliberadamente ignorante de todo lo que ocurre encima.

flowchart TB
P[Pager con transacciones y diario] -->|leer 4096 bytes en el desplazamiento N| V[Capa VFS]
V --> U[Implementacion unix]
V --> W[Implementacion win32]
V --> M[Implementacion en memoria]
V --> O[Implementacion sobre OPFS]
V --> K[Implementacion sobre almacen clave valor]
style V fill:#f9e2af,color:#11111b
style O fill:#a6e3a1,color:#11111b
style K fill:#a6e3a1,color:#11111b

Merece la pena enunciar también lo que esta capa no sabe, porque la lista es larga y sorprendentemente liberadora. No sabe qué es una tabla, ni una fila, ni un índice, ni una transacción. No conoce el SQL que originó la petición. No distingue una lectura de índice de una lectura de datos. Lo único que intuye del mundo de arriba es que además del fichero principal existen otros ficheros auxiliares —el diario, los temporales— cuyos nombres se derivan del principal por convención, y ni siquiera necesita entender para qué sirven: le basta con saber crearlos, escribirlos y borrarlos.

Esa ignorancia es deliberada y tiene una consecuencia práctica que verás en la lección siguiente. Como los ficheros auxiliares son ficheros de pleno derecho, cualquier implementación tiene que poder crear más de uno por base de datos, y en entornos donde los ficheros son un recurso escaso y reservado por adelantado —que es exactamente el caso de una de las opciones de OPFS— hay que dimensionar el conjunto contando el diario y los temporales, no solo las bases. Quien reserva sitio para dos bases y luego se pregunta por qué falla la tercera operación ha olvidado que el pager pide ficheros que él nunca nombró.

Esa estrechez es la propiedad clave y conviene medirla. El vocabulario completo que el motor necesita del mundo exterior cabe en tres ideas: leer un rango de bytes, escribir un rango de bytes y coordinarse con otros que quieran hacer lo mismo. Todo lo demás —crear el fichero, saber su tamaño, truncarlo, borrarlo, preguntar si existe, obtener bytes aleatorios y la hora— es accesorio. Un contrato de ese tamaño puede implementarse sobre casi cualquier cosa que sepa persistir bytes, y esa es literalmente la razón por la que este nivel es posible.

Las tres estructuras y sus operaciones

El contrato se materializa en tres tipos. Uno describe la plataforma y sus operaciones globales sobre nombres. Otro representa un fichero abierto. El tercero es la tabla de funciones que actúan sobre ese fichero abierto.

struct sqlite3_vfs {
  int  iVersion, szOsFile, mxPathname;
  const char *zName;                    /* el nombre con el que se registra */
  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, int flags, int *pOut);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zIn, int nOut, char *zOut);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  /* ... y las de carga dinamica, que en WebAssembly quedan a nulo ... */
};

struct sqlite3_io_methods {
  int  iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead) (sqlite3_file*, void *buf, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void *buf, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int lockLevel);
  int (*xUnlock)(sqlite3_file*, int lockLevel);
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* xShmMap, xShmLock, xShmBarrier y xShmUnmap para la memoria compartida del WAL */
};

Cuatro observaciones sobre esta tabla justifican la mitad de las dificultades del nivel. La primera: xRead y xWrite reciben un desplazamiento absoluto de sesenta y cuatro bits, de modo que la implementación no mantiene una posición de lectura y no necesita nada parecido a un cursor de fichero. La segunda: xLock y xUnlock no son un cerrojo binario sino una escalera de estados —ninguno, compartido, reservado, pendiente, exclusivo— cuyo cumplimiento es lo que permite que varios lectores coexistan con un escritor que aún no ha empezado a escribir. La tercera: xSync es el único punto donde se juega la durabilidad de todo el sistema, y en el navegador es también el más débil. Y la cuarta, la más interesante en clave de rendimiento, es xDeviceCharacteristics.

Detente un momento en la escalera de bloqueos, porque es la parte del contrato que peor se traduce al navegador. Los cinco estados no son caprichosos: el estado compartido permite leer y admite varios ocupantes; el reservado señala la intención de escribir sin impedir que los lectores actuales terminen; el pendiente cierra la puerta a lectores nuevos mientras espera que salgan los antiguos; y solo el exclusivo permite tocar las páginas de datos. Toda la concurrencia de lectores frente a escritor que SQLite ofrece está en esa gradación, y toda ella descansa en que el medio subyacente sepa distinguir un bloqueo compartido de uno exclusivo. Cuando el medio solo sabe conceder acceso exclusivo, como ocurre con el manejador síncrono del nivel 10, la escalera se aplana y la concurrencia desaparece por construcción, no por un fallo de implementación.

Repara también en las operaciones que parecen triviales y no lo son en este entorno. xFullPathname debe convertir un nombre en su forma canónica, pero en un almacenamiento sin rutas de verdad esa canonicalización es una convención que inventa la propia implementación. xAccess responde si un nombre existe y si es escribible, algo que en un almacén de clave y valor exige mantener metadatos propios. Y xRandomness y las funciones de tiempo tienen que resolverse con las fuentes del navegador, cuya resolución temporal está deliberadamente degradada por motivos de privacidad. Ninguna de estas es difícil; todas son sitios donde una implementación descuidada introduce diferencias sutiles de comportamiento.

Registrar, seleccionar y envolver

Una implementación se da de alta en tiempo de ejecución y el motor mantiene una lista con todas las registradas, cada una con su nombre. Elegir cuál usa una conexión concreta admite tres vías, en orden creciente de prioridad: la que esté marcada como predeterminada, la que se pase explícitamente al abrir, y la que indique el propio nombre del fichero cuando se usa la sintaxis de URI. Esta última es la que verás por todas partes en el mundo del navegador, y también funciona al adjuntar una base adicional a una conexión ya abierta.

// Comprobar disponibilidad antes de asumir nada
if (sqlite3.capi.sqlite3_vfs_find("opfs")) {
  const db = new sqlite3.oo1.DB("file:cuaderno.sqlite3?vfs=opfs", "c");
  // Distintas conexiones del mismo proceso pueden usar implementaciones distintas
}

En C el mecanismo es igual de directo, y verlo ayuda a entender que la elección es de tiempo de ejecución y no de compilación: se busca una implementación por nombre y se registra, opcionalmente marcándola como predeterminada para todas las conexiones futuras.

/* Cambiar la predeterminada del proceso entero */
sqlite3_vfs_register(sqlite3_vfs_find("unix-excl"), 1);

/* O elegirla solo para esta conexion */
int rc = sqlite3_open_v2("demo.db", &db, SQLITE_OPEN_READWRITE, "unix-none");

Hay una consecuencia de diseño que la gente descubre tarde y que abre un abanico entero de técnicas: como el contrato es simétrico, una implementación puede envolver a otra, interceptar las llamadas, hacer algo con ellas y delegar. El árbol de fuentes del proyecto trae varios ejemplos de estas capas intermedias, y merece la pena conocerlos porque el catálogo revela hasta dónde llega la palanca.

Por qué esta es exactamente la palanca

Hay un último aspecto del contrato que se aprecia mejor mirando la pila entera de una vez, y es dónde se decide cada propiedad que le importa a tu producto. La corrección del SQL se decide arriba, en el analizador y el generador de código, y no depende del medio. La atomicidad se decide en el pager y depende del medio solo a través de las banderas que la implementación declara. La velocidad y la concurrencia se deciden abajo, íntegramente en esta capa, y es la razón por la que la lección siguiente puede plantearse como una elección de rendimiento sin que nada de lo aprendido sobre consultas se ponga en duda.

Reúne ahora las piezas. El motor entero está aislado tras una interfaz de una docena de funciones. Esa interfaz no menciona rutas del sistema, ni descriptores, ni llamadas concretas del núcleo: menciona bytes y desplazamientos. Se registra en tiempo de ejecución, admite varias implementaciones simultáneas y permite componerlas. Y la propia compilación oficial a WebAssembly demuestra el punto de la forma más elocuente posible: sus implementaciones para el navegador están escritas íntegramente en JavaScript, conectadas al motor a través de esa misma tabla de funciones que en Unix apunta a llamadas al sistema.

Ese hecho merece subrayarse porque desactiva una objeción frecuente. Nadie tuvo que modificar el motor para que hablara con OPFS: alguien escribió unas cuantas funciones en JavaScript con la firma adecuada, las conectó a la tabla y el motor siguió creyendo que estaba hablando con un sistema operativo. La cantidad de código C que hubo que tocar para que SQLite persistiera en un navegador es, en lo esencial, ninguna.

Queda una pieza del contrato que no es una función pero condiciona todo lo demás: estas operaciones son síncronas. Cuando el pager llama a xRead, espera que los bytes estén en el búfer al retornar. No hay ninguna versión del contrato que admita devolver una promesa, y no la hay porque el motor está a mitad de ejecutar bytecode con su pila viva y no tiene forma de suspenderse. Todo lo que verás en la lección siguiente —por qué el almacenamiento del navegador que sí es síncrono solo existe dentro de un Worker, por qué usar un almacén asíncrono obliga a transformar el binario o a apoyarse en la suspensión de pilas, por qué leer bloquea el fichero— se deduce de esa única línea del contrato.