docs(cayenne): metastore auto_vacuum defaults to incremental, and a bare VACUUM cannot migrate an existing file

[claudespice]

Summary

Two wrong claims in the cayenne_metastore_auto_vacuum row of the Cayenne runtime.params table.

1. The default is no longer none (vNext). spiceai/spiceai#13651 flipped SqliteMetastoreConfig::default().auto_vacuum from SqliteAutoVacuum::None to SqliteAutoVacuum::Incremental (crates/cayenne/src/metastore/sqlite.rs, asserted by test_auto_vacuum_defaults_to_incremental). The docs still say Defaults to none, which inverts what a stock runtime does: incremental page reclamation is now on by default, and the accompanying cayenne_metastore_incremental_vacuum_pages cap (already documented) is what bounds each write-lock hold. The same row's "An unrecognized value logs a warning and falls back to none" is wrong for the same reason — crates/runtime/src/builder.rs leaves metastore_cfg.auto_vacuum on whatever the Default impl holds, and the warning itself says "Keeping the default".

git tag --contains 00cbd761e3 returns nothing, so this half is vNext-only: version-2.0.x, version-2.1.x and version-2.2.x correctly document none (v2.2.0 still ships auto_vacuum: SqliteAutoVacuum::None).

2. The migration sequence is a no-op in every version. All four snapshots said an existing database "needs a full VACUUM to change it". A bare VACUUM preserves whatever auto_vacuum mode the file already has — moving an existing metastore off none takes PRAGMA auto_vacuum = <mode> and then a full VACUUM. An operator following the published guidance would run a VACUUM, see the mode unchanged, and have no way to tell why. That correction applies to every version, so it lands in all four files.

The runtime now warns at startup when it opens a metastore created under the old none default, and that warning links to this page — which, before this PR, told the reader the opposite of what the warning says.

What changed

• vNext: default corrected to incremental; unrecognized-value fallback corrected to "keeps the incremental default"; the real migration sequence (PRAGMA auto_vacuum = INCREMENTAL; VACUUM;, with the runtime's startup warning noted) replaces the bare-VACUUM guidance.
• version-2.0.x / version-2.1.x / version-2.2.x: default left at none (correct for those releases); only the migration sequence corrected.

Source refs

• fix(cayenne): reclaim inline tombstones, and return the freed metastore pages spiceai#13651 — fix(cayenne): reclaim inline tombstones, and return the freed metastore pages (commit 00cbd761e3, 2026-08-28, no release tag)
• crates/cayenne/src/metastore/sqlite.rs — impl Default for SqliteMetastoreConfig, the auto_vacuum field doc, and the legacy-metastore startup warning
• crates/runtime/src/builder.rs — CAYENNE_METASTORE_AUTO_VACUUM_PARAM parsing (invalid value → keep default)

Test plan

• cd website && npm run build passes
• Versioned-docs propagation checked — grep -rn "an existing database needs a full" docs/ versioned_docs/ returns 0 hits; cayenne_metastore_auto_vacuum appears in exactly these 4 files
• Files updated: 4 (matches the diff)

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: claudespice

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[github-actions]

🚀 deployed to https://56b029fc.spiceai-org-website.pages.dev

[claudespice]

@copilot review

[Copilot]

@copilot review

Reviewed the current PR changes. No high-confidence issues were found that require code changes.

[Copilot]

🟡 Changes recommended

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Corrects Cayenne metastore auto-vacuum defaults and migration guidance across current and versioned documentation.

Changes:

• Documents the vNext incremental default and fallback behavior.
• Replaces bare VACUUM guidance with the required pragma sequence.

File summaries

File	Description
website/docs/.../cayenne/index.md	Updates current behavior and migration steps.
website/versioned_docs/version-2.0.x/.../index.md	Corrects migration guidance.
website/versioned_docs/version-2.1.x/.../index.md	Corrects migration guidance.
website/versioned_docs/version-2.2.x/.../index.md	Corrects migration guidance.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 4
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🚀 deployed to https://ba58a7d9.spiceai-org-website.pages.dev