Banco de dados

No Notarium, as notas são arquivos, e o índice de busca e o grafo são reconstruídos a partir deles. Mas parte do estado não pode ser derivada dos arquivos: quem a guarda é um banco de metadados (meta) separado. Por padrão, é um arquivo SQLite dentro da raiz de dados — <DATA_DIR>/meta.db; a variável META_DB_URL só é necessária para apontar para um Postgres externo.

O que o banco de metadados guarda

Nada disso pode ser reconstruído apenas a partir dos arquivos .md — por isso o banco de metadados deve sempre ser incluído no seu backup. Há também um registro de espaços nesse banco, mas ele é derivado: a identidade de um espaço vive em um arquivo-marcador na raiz dele e se recupera por uma varredura (File-first). Já os índices derivados do motor (<DATA_DIR>/engine), se forem perdidos, simplesmente se reconstroem a partir dos arquivos na próxima inicialização.

Para saber mais sobre as versões e de onde elas vêm, veja Conceitos: versionamento.

Esquema e migrações

Quem mantém o esquema do banco de metadados é a própria aplicação: as migrações são aplicadas na inicialização, e não existe um comando à parte para elas. O banco carrega dentro de si um registro das migrações já aplicadas nele — é por ele que um build sabe com o que está lidando.

A inicialização aceita exatamente três estados:

• banco vazio — o esquema base é criado, e a entrada no registro é gravada na mesma transação;
• banco cujo registro é um prefixo exato do esperado — versões, nomes e checksums são conferidos e, então, a parte que falta é aplicada;
• banco não vazio e sem registro — a inicialização é abortada (fail closed), antes de qualquer alteração de esquema ou consulta da aplicação.

Esse último caso é deliberado. Um build não adivinha a versão de um banco que não reconhece, nem carimba o registro por conta própria: isso corromperia os dados em silêncio. Se for justamente esse o banco que você tem em mãos (uma instância anterior ao esquema base, digamos), primeiro atualize e verifique-o pelo procedimento padrão da versão dele, e só então o traga através dessa fronteira.

SQLite (padrão)

Zero configuração: por padrão, o banco de metadados é sqlite:<DATA_DIR>/meta.db, ou seja, um arquivo no volume /data. Não é preciso um serviço separado, e não há nada para configurar. Isso basta para uma instância pessoal e uma equipe pequena em um único contêiner.

Postgres (para uma equipe e estado compartilhado)

Para tirar o estado de dentro do contêiner — visando armazenamento compartilhado, tolerância a falhas ou manutenção — aponte para o Postgres:

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

Você precisa do Postgres quando o estado deve viver de forma independente do ciclo de vida do contêiner. As notas em si continuam sendo arquivos em <DATA_DIR>/spaces — para o banco vai apenas o que não pode ser derivado delas.