База данных

Заметки в Notarium — это файлы, а поисковый индекс и граф из них пересобираются. Но часть состояния из файлов не выводится: её хранит отдельная служебная (meta) БД. По умолчанию это SQLite-файл под корнем данных — <DATA_DIR>/meta.db; переменная META_DB_URL нужна только чтобы указать внешний Postgres.

Что хранит служебная БД

Восстановить это из одних .md-файлов нельзя — потому служебную БД обязательно включают в бэкап. Реестр пространств в этой БД тоже есть, но он производный: идентичность пространства живёт в файле-маркере в его корне и восстанавливается сканом (File-first). Производные индексы движка (<DATA_DIR>/engine) при потере просто пересобираются из файлов при следующем запуске.

О самих версиях и их происхождении — Концепции: версии.

Схема и миграции

Схему служебной БД ведёт само приложение: миграции применяются при старте, отдельной команды для них нет. Внутри БД лежит реестр применённых миграций — по нему сборка понимает, с чем имеет дело.

Стартом принимаются ровно три состояния:

• пустая БД — разворачивается базовая схема, запись в реестр делается той же транзакцией;
• БД, чей реестр — точный префикс ожидаемого — сверяются версии, имена и контрольные суммы, затем применяется недостающий хвост;
• непустая БД без реестра — старт падает закрыто, до любых изменений схемы и запросов приложения.

Последнее — намеренно. Сборка не угадывает версию чужой БД и не проставляет отметку сама: это молча испортило бы данные. Если у вас на руках такая база (например, инстанс старее базовой схемы), сначала обновите и проверьте его штатной процедурой его версии, и только потом переносите через эту границу.

SQLite (по умолчанию)

Без настройки: по умолчанию служебная БД — это sqlite:<DATA_DIR>/meta.db, то есть файл на томе /data. Отдельного сервиса не нужно, задавать ничего не надо. Этого достаточно для персонального инстанса и небольшой команды на одном контейнере.

Postgres (для команды и общего состояния)

Чтобы вынести состояние за пределы контейнера — ради общего хранилища, отказоустойчивости или обслуживания — укажите Postgres:

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

Postgres нужен, если состояние должно жить независимо от жизненного цикла контейнера. При этом сами заметки по-прежнему остаются файлами под <DATA_DIR>/spaces — в БД уходит только невыводимое из них.