Migrate

Handle schema version mismatches when upgrading cqs.

Process

1. Check current schema version

cqs stats 2>&1

If it works normally, no migration needed. If you see a schema error, continue.

2. Identify the mismatch

Errors tell you the versions:

• •SchemaMismatch(path, from, to): Index is at version from, cqs expects to. Auto-migration was attempted but no migration path exists.
• •SchemaNewerThanCq(version): Index was created by a newer cqs version. Update your binary.

3. Attempt migration

cqs attempts auto-migration when it opens the database. If you're seeing SchemaMismatch, it means no migration path exists for that version jump.

Check available migrations:

grep -n "migrate_v" src/store/migrations.rs

4. Rebuild if no migration path

When auto-migration isn't available, the only option is a full rebuild:

# Back up the old index (just in case)
cp -r .cq/ .cq.backup/

# Delete and rebuild
rm -rf .cq/
cqs init
cqs index

This re-parses all source files and re-embeds them. Notes in docs/notes.toml are preserved (they live outside .cq/).

5. Rebuild references too

References have their own databases at the same schema version:

cqs ref list

For each reference:

cqs ref update <name>

If that fails with schema errors, remove and re-add:

cqs ref remove <name>
cqs ref add <name> <source_path> --weight <weight>

6. Verify

cqs stats

Should show the current schema version and correct chunk counts.

7. Clean up

rm -rf .cq.backup/

Notes

• •.cq/ is gitignored — rebuilding only costs time, not data
• •Notes (docs/notes.toml) are never lost — they're separate from the index
• •Schema version is stored in metadata table: SELECT value FROM metadata WHERE key = 'schema_version'
• •Current version: v10 (check src/store/helpers.rs:CURRENT_SCHEMA_VERSION)