Reconcile the schema/migration story across code and four documents #68

New Issue

clawbot · 2026-08-09T03:42:24+02:00

clawbot commented

2026-08-09 03:42:24 +02:00

Four documents say vaultik has no migrations; the code has a numbered
schema-application framework with a schema_migrations table. And the one
document that tells contributors what to edit names a file that does not
exist.

The code

internal/database/database.go:35 — //go:embed schema/*.sql
collectMigrations (:303), bootstrapMigrationsTable (:324),
applyMigrations (:356), inserting into schema_migrations (:405)
Files present: internal/database/schema/000.sql (creates
schema_migrations) and internal/database/schema/001.sql (all ten
tables)

The docs

README:390-392 — "No database migrations. If the local SQLite
schema changes between versions, delete the local database…"
README:462-465 — roadmap: "Schema migrations. Currently nonexistent"
docs/DATAMODEL.md:8-12 — "No Migration Support (pre-1.0)"
AGENTS.md:105-109 — "Pre-1.0: NEVER write database migrations… just
change schema.sql"

schema.sql does not exist — find . -name schema.sql returns
nothing. A contributor or agent following AGENTS.md today edits a
nonexistent file. That is the concrete bug here.

Framing

These are less contradictory than they look, and the fix should not
overcorrect. The standing project decision is that migrations are not
supported: schema upgrades are handled by deleting the local state file
and re-running a full backup. That decision stands and is not up for
revision in this issue.

What exists in the code is a schema application mechanism (apply
numbered files to a fresh database and record which ran), not an upgrade
path between released versions. The docs are describing the policy; the
code is describing the bootstrap. Both can be true — the wording just has
to stop implying the schema_migrations table is absent.

Definition of done

AGENTS.md:105-109 names the real files (internal/database/schema/ NNN.sql) and describes the actual procedure for changing the schema
pre-1.0. The string schema.sql no longer appears anywhere.
README:390-392, README:462-465, and docs/DATAMODEL.md:8-12 are
reworded to distinguish "no supported upgrade path between versions —
delete the local index and re-back-up" (the policy, unchanged) from
the numbered schema files and schema_migrations table that do exist.
No document may assert the table does not exist.
One document owns the explanation; the others link to it.
The policy itself is unchanged: no migration steps are to be written,
and the local index remains disposable pre-1.0.
Note in the docs that AGENTS.md's "disposable until 1.0 ships and is
tagged" clause expires on tagging, so the question returns at release
time. Do not attempt to answer it now.
Docs only, no code changes. make fmt over changed markdown;
make check green.

Four documents say vaultik has no migrations; the code has a numbered schema-application framework with a `schema_migrations` table. And the one document that tells contributors what to edit names a file that does not exist. ## The code - `internal/database/database.go:35` — `//go:embed schema/*.sql` - `collectMigrations` (:303), `bootstrapMigrationsTable` (:324), `applyMigrations` (:356), inserting into `schema_migrations` (:405) - Files present: `internal/database/schema/000.sql` (creates `schema_migrations`) and `internal/database/schema/001.sql` (all ten tables) ## The docs - README:390-392 — "**No database migrations.** If the local SQLite schema changes between versions, delete the local database…" - README:462-465 — roadmap: "**Schema migrations.** Currently nonexistent" - `docs/DATAMODEL.md:8-12` — "**No Migration Support (pre-1.0)**" - `AGENTS.md:105-109` — "Pre-1.0: NEVER write database migrations… just change `schema.sql`" **`schema.sql` does not exist** — `find . -name schema.sql` returns nothing. A contributor or agent following `AGENTS.md` today edits a nonexistent file. That is the concrete bug here. ## Framing These are less contradictory than they look, and the fix should not overcorrect. The standing project decision is that migrations are **not** supported: schema upgrades are handled by deleting the local state file and re-running a full backup. That decision stands and is not up for revision in this issue. What exists in the code is a schema *application* mechanism (apply numbered files to a fresh database and record which ran), not an *upgrade path* between released versions. The docs are describing the policy; the code is describing the bootstrap. Both can be true — the wording just has to stop implying the `schema_migrations` table is absent. ## Definition of done 1. `AGENTS.md:105-109` names the real files (`internal/database/schema/ NNN.sql`) and describes the actual procedure for changing the schema pre-1.0. The string `schema.sql` no longer appears anywhere. 2. README:390-392, README:462-465, and `docs/DATAMODEL.md:8-12` are reworded to distinguish "no supported upgrade path between versions — delete the local index and re-back-up" (the policy, unchanged) from the numbered schema files and `schema_migrations` table that do exist. No document may assert the table does not exist. 3. One document owns the explanation; the others link to it. 4. The policy itself is unchanged: no migration steps are to be written, and the local index remains disposable pre-1.0. 5. Note in the docs that `AGENTS.md`'s "disposable until 1.0 ships and is tagged" clause expires on tagging, so the question returns at release time. Do not attempt to answer it now. 6. Docs only, no code changes. `make fmt` over changed markdown; `make check` green.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:42:24 +02:00

clawbot referenced this issue

2026-08-09 03:44:09 +02:00

Documentation accuracy sweep: undocumented behavior and stale claims #74

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/vaultik#68