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.
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
docs/DATAMODEL.md now owns the explanation, separating the unchanged policy (no upgrade path between versions; delete the local index and re-back-up) from the schema bootstrap that exists (internal/database/schema/000.sql/001.sql and the schema_migrations table). README (caveat + roadmap) and AGENTS.md reworded to match and link there; AGENTS.md names the real file and notes the disposability clause expires on tagging. No document asserts the table is absent. Docs only; make check green.
schema.sql as a substring remains in REPO_POLICIES.md (001_schema.sql, cross-project policy synced from an authoritative source — out of scope) and in a database_test.go fixture (code; done-item 6 is docs-only). Detail in the PR body.
model: claude-opus-4-8
PR: https://git.eeqj.de/sneak/vaultik/pulls/146
`docs/DATAMODEL.md` now owns the explanation, separating the unchanged policy (no upgrade path between versions; delete the local index and re-back-up) from the schema bootstrap that exists (`internal/database/schema/000.sql`/`001.sql` and the `schema_migrations` table). README (caveat + roadmap) and `AGENTS.md` reworded to match and link there; `AGENTS.md` names the real file and notes the disposability clause expires on tagging. No document asserts the table is absent. Docs only; `make check` green.
`schema.sql` as a substring remains in `REPO_POLICIES.md` (`001_schema.sql`, cross-project policy synced from an authoritative source — out of scope) and in a `database_test.go` fixture (code; done-item 6 is docs-only). Detail in the PR body.
model: claude-opus-4-8
wrong. migrations are supported. we just don't have/add any before 1.0. post-1.0, we will absolutely do migrations on the local database on application update. it's just that today there is zero installed base.
wrong. migrations *are* supported. we just don't have/add any before 1.0. post-1.0, we will absolutely do migrations on the local database on application update. it's just that today there is zero installed base.
Correction (sneak, 2026-09-25): vaultik supports migrations. None are written before 1.0 only because nothing is installed anywhere yet. After 1.0, the local database is migrated when the application is updated.
What landed from this issue (#146) says the opposite: the documents call "no upgrade path between versions; delete the local index and back up again" the standing policy. That is wrong and gets reworded.
Definition of done (replaces the one above)
docs/DATAMODEL.md, the README (the caveat and the roadmap) and AGENTS.md say: migrations are supported; none are added before 1.0 because there is no installed base; after 1.0 the local database is migrated on update.
No document says vaultik does not support migrations.
One docs-only PR to next, passed by an independent reviewer.
Model: opus-5-5
Correction (sneak, 2026-09-25): vaultik supports migrations. None are written before 1.0 only because nothing is installed anywhere yet. After 1.0, the local database is migrated when the application is updated.
What landed from this issue (https://git.eeqj.de/sneak/vaultik/pulls/146) says the opposite: the documents call "no upgrade path between versions; delete the local index and back up again" the standing policy. That is wrong and gets reworded.
## Definition of done (replaces the one above)
- `docs/DATAMODEL.md`, the README (the caveat and the roadmap) and `AGENTS.md` say: migrations are supported; none are added before 1.0 because there is no installed base; after 1.0 the local database is migrated on update.
- No document says vaultik does not support migrations.
- One docs-only PR to `next`, passed by an independent reviewer.
Model: opus-5-5
Implementer brief for the rework. The definition of done is #68 (comment).
The story to tell, matching the code: the numbered files in internal/database/schema/ are migrations. schema_migrations records which ones have run, and opening a database applies any that have not. So migrations are supported. Before 1.0 none are added (a schema change edits 001.sql directly), because nothing is installed anywhere yet. After 1.0 each schema change is a new numbered file, and an existing local database is migrated when the application is updated. Canonical REPO_POLICIES.md:363-371 already says this; leave it alone.
Passages on next (d24f5dc) that say the opposite:
docs/DATAMODEL.md:9-31, the section that owns the explanation. Rewrite it.
README.md:562-568, the caveat. README.md:634-639, the roadmap entry. Both link to the DATAMODEL section.
AGENTS.md:105-115, policy 13.
CLAUDE.md:33. This is the owner's file, so make the smallest edit that stops it saying migrations are not needed, and list it in the PR body as a disclosure.
A practical note may stay: until 1.0 a schema change can make a pre-1.0 index unusable, and vaultik database delete plus a full backup recovers. It must not be framed as migrations being unsupported.
Docs only, no code. Run make fmt over the changed markdown; make check green. One PR to next.
Model: opus-5-5
Implementer brief for the rework. The definition of done is https://git.eeqj.de/sneak/vaultik/issues/68#issuecomment-103108.
The story to tell, matching the code: the numbered files in `internal/database/schema/` are migrations. `schema_migrations` records which ones have run, and opening a database applies any that have not. So migrations are supported. Before 1.0 none are added (a schema change edits `001.sql` directly), because nothing is installed anywhere yet. After 1.0 each schema change is a new numbered file, and an existing local database is migrated when the application is updated. Canonical `REPO_POLICIES.md:363-371` already says this; leave it alone.
Passages on `next` (`d24f5dc`) that say the opposite:
- `docs/DATAMODEL.md:9-31`, the section that owns the explanation. Rewrite it.
- `README.md:562-568`, the caveat. `README.md:634-639`, the roadmap entry. Both link to the DATAMODEL section.
- `AGENTS.md:105-115`, policy 13.
- `CLAUDE.md:33`. This is the owner's file, so make the smallest edit that stops it saying migrations are not needed, and list it in the PR body as a disclosure.
A practical note may stay: until 1.0 a schema change can make a pre-1.0 index unusable, and `vaultik database delete` plus a full backup recovers. It must not be framed as migrations being unsupported.
Docs only, no code. Run `make fmt` over the changed markdown; `make check` green. One PR to `next`.
Model: opus-5-5
The documents now say what the definition of done asks: migrations are supported, none are added before 1.0, and after 1.0 the local database is migrated on update. docs/DATAMODEL.md owns the explanation; the README and AGENTS.md link to it. CLAUDE.md line 33 gets a one-line edit (owner's file).
Model: opus-5-5
PR: https://git.eeqj.de/sneak/vaultik/pulls/205
The documents now say what the definition of done asks: migrations are supported, none are added before 1.0, and after 1.0 the local database is migrated on update. `docs/DATAMODEL.md` owns the explanation; the README and `AGENTS.md` link to it. `CLAUDE.md` line 33 gets a one-line edit (owner's file).
Model: opus-5-5
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Four documents say vaultik has no migrations; the code has a numbered
schema-application framework with a
schema_migrationstable. And the onedocument that tells contributors what to edit names a file that does not
exist.
The code
internal/database/database.go:35—//go:embed schema/*.sqlcollectMigrations(:303),bootstrapMigrationsTable(:324),applyMigrations(:356), inserting intoschema_migrations(:405)internal/database/schema/000.sql(createsschema_migrations) andinternal/database/schema/001.sql(all tentables)
The docs
schema changes between versions, delete the local database…"
docs/DATAMODEL.md:8-12— "No Migration Support (pre-1.0)"AGENTS.md:105-109— "Pre-1.0: NEVER write database migrations… justchange
schema.sql"schema.sqldoes not exist —find . -name schema.sqlreturnsnothing. A contributor or agent following
AGENTS.mdtoday edits anonexistent 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_migrationstable is absent.Definition of done
AGENTS.md:105-109names the real files (internal/database/schema/ NNN.sql) and describes the actual procedure for changing the schemapre-1.0. The string
schema.sqlno longer appears anywhere.docs/DATAMODEL.md:8-12arereworded 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_migrationstable that do exist.No document may assert the table does not exist.
and the local index remains disposable pre-1.0.
AGENTS.md's "disposable until 1.0 ships and istagged" clause expires on tagging, so the question returns at release
time. Do not attempt to answer it now.
make fmtover changed markdown;make checkgreen.PR: #146
docs/DATAMODEL.mdnow owns the explanation, separating the unchanged policy (no upgrade path between versions; delete the local index and re-back-up) from the schema bootstrap that exists (internal/database/schema/000.sql/001.sqland theschema_migrationstable). README (caveat + roadmap) andAGENTS.mdreworded to match and link there;AGENTS.mdnames the real file and notes the disposability clause expires on tagging. No document asserts the table is absent. Docs only;make checkgreen.schema.sqlas a substring remains inREPO_POLICIES.md(001_schema.sql, cross-project policy synced from an authoritative source — out of scope) and in adatabase_test.gofixture (code; done-item 6 is docs-only). Detail in the PR body.model: claude-opus-4-8
clawbot referenced this issue2026-09-22 00:42:41 +02:00
wrong. migrations are supported. we just don't have/add any before 1.0. post-1.0, we will absolutely do migrations on the local database on application update. it's just that today there is zero installed base.
Correction (sneak, 2026-09-25): vaultik supports migrations. None are written before 1.0 only because nothing is installed anywhere yet. After 1.0, the local database is migrated when the application is updated.
What landed from this issue (#146) says the opposite: the documents call "no upgrade path between versions; delete the local index and back up again" the standing policy. That is wrong and gets reworded.
Definition of done (replaces the one above)
docs/DATAMODEL.md, the README (the caveat and the roadmap) andAGENTS.mdsay: migrations are supported; none are added before 1.0 because there is no installed base; after 1.0 the local database is migrated on update.next, passed by an independent reviewer.Model: opus-5-5
Implementer brief for the rework. The definition of done is #68 (comment).
The story to tell, matching the code: the numbered files in
internal/database/schema/are migrations.schema_migrationsrecords which ones have run, and opening a database applies any that have not. So migrations are supported. Before 1.0 none are added (a schema change edits001.sqldirectly), because nothing is installed anywhere yet. After 1.0 each schema change is a new numbered file, and an existing local database is migrated when the application is updated. CanonicalREPO_POLICIES.md:363-371already says this; leave it alone.Passages on
next(d24f5dc) that say the opposite:docs/DATAMODEL.md:9-31, the section that owns the explanation. Rewrite it.README.md:562-568, the caveat.README.md:634-639, the roadmap entry. Both link to the DATAMODEL section.AGENTS.md:105-115, policy 13.CLAUDE.md:33. This is the owner's file, so make the smallest edit that stops it saying migrations are not needed, and list it in the PR body as a disclosure.A practical note may stay: until 1.0 a schema change can make a pre-1.0 index unusable, and
vaultik database deleteplus a full backup recovers. It must not be framed as migrations being unsupported.Docs only, no code. Run
make fmtover the changed markdown;make checkgreen. One PR tonext.Model: opus-5-5
PR: #205
The documents now say what the definition of done asks: migrations are supported, none are added before 1.0, and after 1.0 the local database is migrated on update.
docs/DATAMODEL.mdowns the explanation; the README andAGENTS.mdlink to it.CLAUDE.mdline 33 gets a one-line edit (owner's file).Model: opus-5-5