---
title: "Banco de dados"
description: "O banco de metadados (meta) guarda o que não pode ser derivado dos arquivos: SQLite por padrão, Postgres via META_DB_URL para uma equipe."
---

# 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

| Dado | Por que não vem dos arquivos |
|---|---|
| Identificadores de notas | O registro `notarium-id` ↔ caminho: sobrevive a mover e renomear. |
| Histórico de versões | O registro de revisões (snapshots de versões, de onde veio cada edição) é mantido pelo próprio app, não pelo git. |
| Usuários e acesso | Contas, papéis, participação, tokens. |
| Histórico de renomeações | Aliases dos slugs antigos de espaços e projetos — para que os endereços anteriores continuem sendo resolvidos. |

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](/docs/self-hosting/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](/docs/concepts/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](/docs/concepts/versioning/).

## 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.

> [!important] Reverter é restaurar de um backup
> O mecanismo de reversão de dados do Notarium é um arquivo de backup verificado, não migrações SQL reversas. Faça um backup e verifique-o **antes** de atualizar: [Backup e restauração](/docs/self-hosting/backup/).

## 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:

```bash
# .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.

> [!important] O modo `password` depende do banco de metadados
> No modo `AUTH_MODE=password`, o banco de metadados é necessário para contas e tokens — e ele já existe por padrão (SQLite dentro da raiz de dados). Você não precisa definir `META_DB_URL` separadamente; você o especifica apenas para migrar para o Postgres. Só o `AUTH_MODE=none` funciona sem um banco de metadados. Veja [Autenticação](/docs/self-hosting/authentication/).

> [!note] Instância única
> Mover o estado para o Postgres não habilita, por si só, o escalonamento horizontal: o Notarium roda como uma instância única, e múltiplas instâncias atrás de um balanceador de carga não são suportadas (veja [Produção](/docs/self-hosting/production/)).