Compatibility
Zova reports separate package, C ABI, SQLite, and storage-format versions. Changing one does not imply a change in the others.
| Version | Zova 1.3.0 |
|---|---|
| Package | 1.3.0 |
| C ABI | 1.3.0 |
| Vendored SQLite | 3.53.4 |
| Zova storage format | 12 |
Storage promise
Every Zova 1.x release can migrate databases created by every earlier 1.x release. Format 9—the format written by released Zova 0.26.1—is the only pre-1.0 format guaranteed a migration into 1.x.
Zova 1.0.0 and 1.1.0 wrote format 11. Zova 1.2.0 introduced format 12 for transactional vector change tracking, and 1.3.0 keeps it, so databases written by 1.2.0 open unchanged.
| Source format | v1.3.0 classification | Action |
|---|---|---|
| 12 | current | open normally |
| 11 | migratable | explicitly migrate 11 → 12 |
| 10 | migratable | explicitly migrate 10 → 11 → 12 |
| 9 | migratable | explicitly migrate 9 → 10 → 11 → 12 |
| 8 or older | unsupported legacy | export with a compatible older release |
| newer than 12 | unsupported future | use a compatible newer Zova release |
Opening a database never migrates it. Current files open; migratable files return MigrationRequired; legacy and future files return distinct errors. Each path leaves the source byte-identical.
Probe and migrate
Migration is offline and copy-forward. It writes a new destination and preserves the source:
zova format app.zova
zova migrate app.zova app-format-12.zova
zova format reports the source format, current format, earliest migratable format, compatibility class, and recommended action. Add --json for automation. zova migrate verifies the destination by default; --no-verify skips that final reopen.
Equivalent probe and migrate APIs are available through the C ABI, Rust, Python, Go, and JavaScript bindings. Keep a backup before migrating.
Migration rules
- The destination main database and bound-store siblings must not exist.
- Bound stores migrate as one logical set and are published before the main database.
- Staging needs free space roughly equal to the source set and a filesystem that supports hard links.
- Migration takes an offline write lock while it plans and copies the source set.
- User SQL schema and rows, public identities, objects, vectors, graphs, extension records, store identities, and ordering are preserved.
- Extension-owned tables pass through unchanged and face normal extension validation when the destination opens.
- Plain migration refuses a database whose installed extensions are not bundled with Zova, and publishes nothing. Since 1.3.0, the C ABI's
zova_database_migrate_with_extensionsaccepts the same trusted bundle paths and linked plugin descriptors as open. The high-level bindings do not wrap it yet. - Downgrade migration is unsupported.
An interrupted run can leave destination reservations, published bound stores, and a <destination>.migration-recovery/ directory. Stop every process using those paths, keep the destination and recovery directory together, then run the matching release's ownership-checking recovery script:
python3 scripts/recover-migration.py /path/to/app-format-12.zova
On Windows, use python if python3 is unavailable. The script removes only outputs proven to belong to that migration. If it refuses, preserve the files and investigate—do not force-delete or hand-publish staged files.
Keep artifacts aligned
Use the package, C header, static library, CLI, generated-C companion, and extensions from the same release. Go requires a matching C ABI archive. Since 1.2.0, native and generated-C artifacts both load trusted dynamic extensions on Linux, macOS, and Windows. A bundle must match the host's OS, CPU, deployment target, and runtime ABI.
Read the v1.3.0 release notes, the v1.2.0 release notes, and the API stability contract before upgrading production applications.