Перейти к основному содержимому

Хранилище SQLite

NeoTavern хранит все структурированные данные в одной базе данных SQLite со строгими прагмами, STRICT-таблицами, поиском FTS5 и версионируемыми миграциями.

Настройки базы данных​

Соединение открывается со следующими настройками:

  • foreign_keys = ON — обеспечивается ссылочная целостность.
  • Режим журнала WAL — читатели никогда не блокируются писателями.
  • busy_timeout — конкурирующие писатели ждут, а не падают сразу.
  • synchronous = NORMAL — долговечность с безопасной для WAL производительностью.
  • Подготовленные выражения — все запросы проходят через подготовленные выражения Drizzle; никакой интерполяции сырых SQL-строк.
  • STRICT-таблицы везде, где возможно — SQLite обеспечивает типы столбцов.
  • FTS5 — полнотекстовый поиск по персонажам, чатам и сообщениям.

Стабильные идентификаторы​

У каждой сущности есть стабильный строковый идентификатор, предпочтительно UUIDv7. Идентификаторы никогда не являются индексами массива. Там, где нужна корзина, строки мягко удаляются через deleted_at вместо полного удаления.

Обзор схемы​

Основные таблицы покрывают библиотеку и состояние рантайма: персонажи, персоны, чаты, ветки, сообщения и варианты сообщений, теги, лорбуки и записи лорбуков, пресеты, конфигурации и секреты провайдеров, реестр плагинов с настройками и выдачами возможностей, реестр тем, аудиты контекста промптов, задания импорта и артефакты, а также метаданные кэша.

Для авторов плагинов важны два паттерна:

  • plugin_state хранит состояние, принадлежащее плагину, отдельно от реестра установки, с schema_version для формата данных и revision для compare-and-swap.
  • provider_secrets хранит API-ключи как значения только для записи: из репозитория никогда не выходит ничего, кроме маскированного предпросмотра.

Поиск FTS5​

Виртуальные таблицы characters_fts, chats_fts и messages_fts обеспечивают поиск, построенный с unicode61 и remove_diacritics. Триггеры на INSERT/UPDATE/DELETE поддерживают их синхронизацию транзакционно. Поиск поддерживает префиксные термины (token*), фильтры по тегам и ранжирование релевантности bm25. Полная пересборка доступна на POST /api/v2/search/rebuild.

Миграции​

Каждое изменение схемы поставляется как миграция:

  • Миграции версионированы и идемпотентны — IF NOT EXISTS плюс строгая версия делают повторный запуск безопасным.
  • Миграции выполняются транзакционно; неудачная миграция откатывается целиком.
  • Автоматической миграции down нет. Откат означает восстановление резервной копии до миграции, которую раннер автоматически создаёт для заполненных баз перед опасными миграциями.
  • Чтение данных никогда не запускает скрытые разрушительные изменения.

О том, как работают страховочные резервные копии раннера миграций, см. Резервные копии.

Изоляция плагинов​

Плагины никогда не получают прямое соединение SQLite. Всё сохранение идёт через API хранилища Plugin SDK, которые владеют таблицами plugin_storage и plugin_state от имени плагина. Это держит данные плагинов версионируемыми, отзываемыми и защищёнными от случайностей сырого SQL. Об API хранилища см. Plugin SDK.

Что никогда не попадает в базу данных​

  • Изображения и аудио хранятся на диске, а не как BLOB в основной базе. См. Файлы и изображения.
  • Неизвестные поля карточек персонажей и метаданные расширений сохраняются в столбце ext и переживают экспорт и импорт.