SQLite 저장소

NeoTavern은 모든 구조화된 데이터를 엄격한 프래그마, STRICT 테이블, FTS5 검색, 버전 마이그레이션을 갖춘 단일 SQLite 데이터베이스에 저장합니다.

데이터베이스 설정

연결은 다음 설정으로 열립니다.

• foreign_keys = ON — 참조 무결성이 강제됩니다.
• WAL 저널 모드 — 작성자가 읽기를 막지 않습니다.
• busy_timeout — 동시 작성자는 즉시 실패하는 대신 기다립니다.
• synchronous = NORMAL — WAL에 안전한 성능으로 내구성을 확보합니다.
• 준비된 문 — 모든 쿼리는 Drizzle의 준비된 문을 거치며 원시 SQL 문자열 보간이 없습니다.
• 가능한 곳에 STRICT 테이블 — SQLite가 열 유형을 강제합니다.
• FTS5 — 캐릭터, 채팅, 메시지 전체 텍스트 검색.

안정적인 ID

모든 엔티티는 안정적인 문자열 ID를 가지며, 가능하면 UUIDv7입니다. ID는 절대 배열 인덱스가 아닙니다. 휴지통이 필요한 곳에서는 행이 제거되는 대신 deleted_at으로 소프트 삭제됩니다.

스키마 개요

주요 테이블은 라이브러리와 런타임 상태를 다룹니다. 캐릭터, 페르소나, 채팅, 브랜치, 메시지와 메시지 변형, 태그, 로어북과 로어 항목, 프리셋, 프로바이더 구성과 비밀, 설정과 능력 부여가 있는 플러그인 레지스트리, 테마 레지스트리, 프롬프트 컨텍스트 감사, 가져오기 작업과 아티팩트, 캐시 메타데이터입니다.

플러그인 작성자에게 중요한 두 가지 패턴이 있습니다.

• plugin_state는 설치 레지스트리와 분리된 플러그인 소유 상태를 저장하며, 데이터 형식용 schema_version과 compare-and-swap용 revision이 있습니다.
• 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 연결을 받지 않습니다. 모든 영속화는 플러그인 SDK의 스토리지 API를 통해 이루어지며, SDK가 플러그인을 대신해 plugin_storage와 plugin_state 테이블을 소유합니다. 덕분에 플러그인 데이터는 버전이 유지되고, 철회 가능하며, 원시 SQL 사고로부터 안전합니다. 스토리지 API는 Plugin SDK를 참조하세요.

데이터베이스에 절대 들어가지 않는 것

• 이미지와 오디오는 메인 데이터베이스에 BLOB으로 저장되지 않고 디스크에 저장됩니다. 파일 및 이미지를 참조하세요.
• 알 수 없는 캐릭터 카드 필드와 확장 메타데이터는 ext 열에 보존되어 내보내기와 가져오기를 통과합니다.