Reconcile the schema/migration docs with the code (closes #68)
check / check (pull_request) Successful in 3m0s

Four documents implied vaultik has no schema-application mechanism and
told contributors to edit a nonexistent `schema.sql`. The code does have
numbered files in `internal/database/schema/` (`000.sql` creates the
`schema_migrations` table, `001.sql` the application tables) that
bootstrap a fresh database.

docs/DATAMODEL.md now owns the explanation, distinguishing the unchanged
policy (no upgrade path between versions; delete the local index and
re-back-up) from the bootstrap mechanism that does exist. README (caveat
and roadmap) and AGENTS.md are reworded to match and link there. AGENTS.md
now names the real file to edit and notes that the pre-1.0 disposability
clause expires on tagging.

Policy is unchanged; docs only.

model: claude-opus-4-8
This commit is contained in:
2026-09-21 19:30:38 +00:00
parent 5927e1aa3d
commit 14e0592c9a
3 changed files with 45 additions and 15 deletions
+13 -7
View File
@@ -457,9 +457,13 @@ Key fields:
sequentially. Restore speed is bound by single-stream throughput.
* **Device nodes, named pipes, and sockets are silently skipped.** Only
regular files, directories, and symlinks are backed up.
* **No database migrations.** If the local SQLite schema changes between
versions, delete the local database (`vaultik database delete`) and run
a full backup. Remote storage is unaffected.
* **No upgrade path between versions.** There is no supported way to carry
an existing local index across a schema change; if the local SQLite
schema changes between versions, delete the local database (`vaultik
database delete`) and run a full backup. Remote storage is unaffected.
(The binary does embed numbered schema files and a `schema_migrations`
table to bootstrap a fresh database — see [`docs/DATAMODEL.md`](docs/DATAMODEL.md)
— but that is not an upgrade path.)
* **Files that change during backup may be inconsistent.** There is no
filesystem snapshot or freeze. If a file is modified between the scan
and chunk phases, the backed-up copy may reflect a partial write.
@@ -529,10 +533,12 @@ priority.
another host" workflow works but isn't documented as a
first-class operation in this README. Worth a dedicated section
once it's settled.
* **Schema migrations.** Currently nonexistent — pre-1.0 schema
changes are handled by `vaultik database delete` plus a full
re-scan. Post-1.0 we'll need a migration story to keep existing
index databases usable across upgrades.
* **Cross-version schema upgrades.** There is no upgrade path between
released versions — pre-1.0 schema changes are handled by `vaultik
database delete` plus a full re-scan (see
[`docs/DATAMODEL.md`](docs/DATAMODEL.md)). Post-1.0 we'll need a
migration story to keep existing index databases usable across
upgrades.
* **Storage backend coverage tests.** S3, file://, and rclone://
all share the Storer interface but the rclone path is the least
exercised in CI.