Base de datos

En Notarium, las notas son archivos, y el índice de búsqueda y el grafo se reconstruyen a partir de ellos. Pero una parte del estado no se puede derivar de los archivos: la conserva una base de datos de metadatos (meta) aparte. Por defecto es un archivo SQLite bajo la raíz de datos — <DATA_DIR>/meta.db; la variable META_DB_URL solo hace falta para apuntar a un Postgres externo.

Qué guarda la base de datos de metadatos

Nada de esto se puede reconstruir solo a partir de los archivos .md — por eso la base de datos de metadatos siempre debe incluirse en tu copia de seguridad. En esta base de datos también hay un registro de espacios, pero es derivado: la identidad de un espacio vive en un archivo marcador en su raíz y se recupera con un escaneo (File-first). Los índices derivados del motor (<DATA_DIR>/engine), si se pierden, simplemente se reconstruyen a partir de los archivos en el siguiente arranque.

Para saber más sobre las versiones y de dónde vienen, consulta Conceptos: versionado.

Esquema y migraciones

El esquema de la base de datos de metadatos es propiedad de la aplicación: las migraciones se aplican al arrancar y no hay ningún comando aparte para ellas. Dentro de la base de datos vive un registro de las migraciones ya aplicadas — así es como una compilación sabe con qué está tratando.

El arranque admite exactamente tres estados:

• una base de datos vacía — se crea el esquema base y la entrada del registro se escribe en la misma transacción;
• una base de datos cuyo registro es un prefijo exacto del esperado — se comprueban versiones, nombres y sumas de verificación, y luego se aplican las migraciones que faltan;
• una base de datos no vacía y sin registro — el arranque falla en modo fail-closed, antes de cualquier cambio de esquema o consulta de la aplicación.

Esto último es deliberado. Una compilación no adivina la versión de una base de datos que no reconoce, ni sella el registro por su cuenta: eso corrompería los datos en silencio. Si lo que tienes entre manos es una base así (por ejemplo, una instancia anterior al esquema base), actualízala y compruébala primero con el procedimiento estándar de su propia versión, y solo después hazla cruzar esta frontera.

SQLite (por defecto)

Sin configuración: por defecto la base de datos de metadatos es sqlite:<DATA_DIR>/meta.db, es decir, un archivo en el volumen /data. No hace falta ningún servicio aparte, ni hay nada que configurar. Esto basta para una instancia personal y un equipo pequeño en un único contenedor.

Postgres (para un equipo y estado compartido)

Para sacar el estado fuera del contenedor — para almacenamiento compartido, tolerancia a fallos o mantenimiento — apunta a Postgres:

# .env
META_DB_URL=postgres://user:pass@db:5432/notarium

Necesitas Postgres cuando el estado debe vivir de forma independiente del ciclo de vida del contenedor. Las notas en sí siguen siendo archivos bajo <DATA_DIR>/spaces — solo lo que no se puede derivar de ellas va a la base de datos.