From d4d9afbb3f20f9277656e544a7f13954ee03fbf0 Mon Sep 17 00:00:00 2001 From: claudespice Date: Sun, 30 Aug 2026 01:20:14 -0700 Subject: [PATCH 1/2] docs(cayenne): metastore auto_vacuum now defaults to incremental, and a bare VACUUM cannot migrate an existing file --- website/docs/components/data-accelerators/cayenne/index.md | 2 +- .../version-2.0.x/components/data-accelerators/cayenne/index.md | 2 +- .../version-2.1.x/components/data-accelerators/cayenne/index.md | 2 +- .../version-2.2.x/components/data-accelerators/cayenne/index.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/components/data-accelerators/cayenne/index.md b/website/docs/components/data-accelerators/cayenne/index.md index 854782261..c985b456c 100644 --- a/website/docs/components/data-accelerators/cayenne/index.md +++ b/website/docs/components/data-accelerators/cayenne/index.md @@ -179,7 +179,7 @@ A global `cayenne_goal_*` setpoint steers only the datasets that run the closed | `cayenne_metastore_busy_timeout_ms` | SQLite metastore `busy_timeout` in milliseconds — how long a blocked connection waits for a lock before erroring. Defaults to `30000`. | | `cayenne_metastore_wal_autocheckpoint_pages` | SQLite metastore WAL auto-checkpoint threshold in pages. `0` disables the inline auto-checkpoint so the WAL is drained off the hot commit path by a dedicated background checkpoint instead. Defaults to `0`. | | `cayenne_metastore_wal_truncate_threshold_mb` | WAL size in megabytes above which the background checkpoint escalates to a TRUNCATE checkpoint to reclaim file space. Defaults to `160`. | -| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. Takes effect only on a fresh database (an existing database needs a full `VACUUM` to change it). Defaults to `none`. Under `incremental`, freed pages are marked reclaimable and reclaimed in bounded batches by the background maintenance pass — see `cayenne_metastore_incremental_vacuum_pages`. An unrecognized value logs a warning and falls back to `none`. | +| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. Defaults to `incremental`, so freed pages are marked reclaimable and reclaimed in bounded batches by the background maintenance pass — see `cayenne_metastore_incremental_vacuum_pages`. An unrecognized value logs a warning and keeps the `incremental` default. SQLite fixes the mode at file creation, so a metastore created while the default was `none` stays on `none` — the runtime warns at startup when it finds one. To move it to `incremental`, stop the runtime, run `PRAGMA auto_vacuum = INCREMENTAL; VACUUM;` against the metastore file, and restart: the pragma alone is a no-op on an existing file, and a bare `VACUUM` keeps the file on `none`. | | `cayenne_metastore_incremental_vacuum_pages` | Freelist pages the background maintenance pass reclaims per tick when the metastore is in `incremental` `auto_vacuum` mode; ignored in every other mode. Defaults to `256`, which is 1 MiB at SQLite's 4 KiB default page size. Reclamation holds the write lock while it relocates pages, so the cap is what keeps each pause short; raise it to drain a large freelist faster at the cost of longer write-lock holds, or set `0` to stop reclaiming without changing the database's `auto_vacuum` mode. | ```yaml diff --git a/website/versioned_docs/version-2.0.x/components/data-accelerators/cayenne/index.md b/website/versioned_docs/version-2.0.x/components/data-accelerators/cayenne/index.md index 59a5019dc..b16e17f49 100644 --- a/website/versioned_docs/version-2.0.x/components/data-accelerators/cayenne/index.md +++ b/website/versioned_docs/version-2.0.x/components/data-accelerators/cayenne/index.md @@ -127,7 +127,7 @@ Set once under the top-level `runtime.params` and applied to every Cayenne-accel | `cayenne_metastore_mmap_mb` | SQLite metastore memory-mapped I/O size in megabytes. Defaults to `1024` (1 GiB). | | `cayenne_metastore_busy_timeout_ms` | SQLite metastore `busy_timeout` in milliseconds — how long a blocked connection waits for a lock before erroring. Defaults to `30000`. | | `cayenne_metastore_wal_autocheckpoint_pages` | SQLite metastore WAL auto-checkpoint threshold in pages; the WAL is checkpointed automatically once it grows past this many pages. Defaults to `10000`. | -| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. Takes effect only on a fresh database (an existing database needs a full `VACUUM` to change it). Defaults to `none`. | +| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation: changing it on an existing metastore takes `PRAGMA auto_vacuum = ` followed by a full `VACUUM` — the pragma alone is a no-op there, and a bare `VACUUM` keeps the file on the mode it already has. Defaults to `none`. | ```yaml runtime: diff --git a/website/versioned_docs/version-2.1.x/components/data-accelerators/cayenne/index.md b/website/versioned_docs/version-2.1.x/components/data-accelerators/cayenne/index.md index 2c104f0c0..cfd69eadc 100644 --- a/website/versioned_docs/version-2.1.x/components/data-accelerators/cayenne/index.md +++ b/website/versioned_docs/version-2.1.x/components/data-accelerators/cayenne/index.md @@ -145,7 +145,7 @@ Set once under the top-level `runtime.params` and applied to every Cayenne-accel | `cayenne_metastore_busy_timeout_ms` | SQLite metastore `busy_timeout` in milliseconds — how long a blocked connection waits for a lock before erroring. Defaults to `30000`. | | `cayenne_metastore_wal_autocheckpoint_pages` | SQLite metastore WAL auto-checkpoint threshold in pages. `0` disables the inline auto-checkpoint so the WAL is drained off the hot commit path by a dedicated background checkpoint instead. Defaults to `0`. | | `cayenne_metastore_wal_truncate_threshold_mb` | WAL size in megabytes above which the background checkpoint escalates to a TRUNCATE checkpoint to reclaim file space. Defaults to `160`. | -| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. Takes effect only on a fresh database (an existing database needs a full `VACUUM` to change it). Defaults to `none`. | +| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation: changing it on an existing metastore takes `PRAGMA auto_vacuum = ` followed by a full `VACUUM` — the pragma alone is a no-op there, and a bare `VACUUM` keeps the file on the mode it already has. Defaults to `none`. | ```yaml runtime: diff --git a/website/versioned_docs/version-2.2.x/components/data-accelerators/cayenne/index.md b/website/versioned_docs/version-2.2.x/components/data-accelerators/cayenne/index.md index 8e1dcaac1..10795abfd 100644 --- a/website/versioned_docs/version-2.2.x/components/data-accelerators/cayenne/index.md +++ b/website/versioned_docs/version-2.2.x/components/data-accelerators/cayenne/index.md @@ -179,7 +179,7 @@ A global `cayenne_goal_*` setpoint steers only the datasets that run the closed | `cayenne_metastore_busy_timeout_ms` | SQLite metastore `busy_timeout` in milliseconds — how long a blocked connection waits for a lock before erroring. Defaults to `30000`. | | `cayenne_metastore_wal_autocheckpoint_pages` | SQLite metastore WAL auto-checkpoint threshold in pages. `0` disables the inline auto-checkpoint so the WAL is drained off the hot commit path by a dedicated background checkpoint instead. Defaults to `0`. | | `cayenne_metastore_wal_truncate_threshold_mb` | WAL size in megabytes above which the background checkpoint escalates to a TRUNCATE checkpoint to reclaim file space. Defaults to `160`. | -| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. Takes effect only on a fresh database (an existing database needs a full `VACUUM` to change it). Defaults to `none`. Under `incremental`, freed pages are marked reclaimable and reclaimed in bounded batches by the background maintenance pass — see `cayenne_metastore_incremental_vacuum_pages`. An unrecognized value logs a warning and falls back to `none`. | +| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation: changing it on an existing metastore takes `PRAGMA auto_vacuum = ` followed by a full `VACUUM` — the pragma alone is a no-op there, and a bare `VACUUM` keeps the file on the mode it already has. Defaults to `none`. Under `incremental`, freed pages are marked reclaimable and reclaimed in bounded batches by the background maintenance pass — see `cayenne_metastore_incremental_vacuum_pages`. An unrecognized value logs a warning and falls back to `none`. | | `cayenne_metastore_incremental_vacuum_pages` | Freelist pages the background maintenance pass reclaims per tick when the metastore is in `incremental` `auto_vacuum` mode; ignored in every other mode. Defaults to `256`, which is 1 MiB at SQLite's 4 KiB default page size. Reclamation holds the write lock while it relocates pages, so the cap is what keeps each pause short; raise it to drain a large freelist faster at the cost of longer write-lock holds, or set `0` to stop reclaiming without changing the database's `auto_vacuum` mode. | ```yaml From 6a9d2b79c91d5827b12c2b4f048e7fc51279b0bb Mon Sep 17 00:00:00 2001 From: claudespice <270518434+claudespice@users.noreply.github.com> Date: Tue, 1 Sep 2026 11:34:32 -0700 Subject: [PATCH 2/2] docs(cayenne): scope the auto_vacuum VACUUM requirement to transitions involving none SQLite only fixes auto_vacuum irreversibly across the none boundary. Measured on SQLite 3.51.0: PRAGMA auto_vacuum takes effect on its own when switching an existing file between full and incremental, while every transition to or from none needs a VACUUM after the pragma. The blanket 'an existing database always needs a full VACUUM' rule therefore overstates the downtime a mode change costs on a large metastore. Also links the SQLite auto_vacuum reference so the file-format and VACUUM requirements are verifiable from the page. --- website/docs/components/data-accelerators/cayenne/index.md | 2 +- .../version-2.0.x/components/data-accelerators/cayenne/index.md | 2 +- .../version-2.1.x/components/data-accelerators/cayenne/index.md | 2 +- .../version-2.2.x/components/data-accelerators/cayenne/index.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/components/data-accelerators/cayenne/index.md b/website/docs/components/data-accelerators/cayenne/index.md index c985b456c..c98dcbe23 100644 --- a/website/docs/components/data-accelerators/cayenne/index.md +++ b/website/docs/components/data-accelerators/cayenne/index.md @@ -179,7 +179,7 @@ A global `cayenne_goal_*` setpoint steers only the datasets that run the closed | `cayenne_metastore_busy_timeout_ms` | SQLite metastore `busy_timeout` in milliseconds — how long a blocked connection waits for a lock before erroring. Defaults to `30000`. | | `cayenne_metastore_wal_autocheckpoint_pages` | SQLite metastore WAL auto-checkpoint threshold in pages. `0` disables the inline auto-checkpoint so the WAL is drained off the hot commit path by a dedicated background checkpoint instead. Defaults to `0`. | | `cayenne_metastore_wal_truncate_threshold_mb` | WAL size in megabytes above which the background checkpoint escalates to a TRUNCATE checkpoint to reclaim file space. Defaults to `160`. | -| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. Defaults to `incremental`, so freed pages are marked reclaimable and reclaimed in bounded batches by the background maintenance pass — see `cayenne_metastore_incremental_vacuum_pages`. An unrecognized value logs a warning and keeps the `incremental` default. SQLite fixes the mode at file creation, so a metastore created while the default was `none` stays on `none` — the runtime warns at startup when it finds one. To move it to `incremental`, stop the runtime, run `PRAGMA auto_vacuum = INCREMENTAL; VACUUM;` against the metastore file, and restart: the pragma alone is a no-op on an existing file, and a bare `VACUUM` keeps the file on `none`. | +| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. Defaults to `incremental`, so freed pages are marked reclaimable and reclaimed in bounded batches by the background maintenance pass — see `cayenne_metastore_incremental_vacuum_pages`. An unrecognized value logs a warning and keeps the `incremental` default. SQLite fixes the mode at file creation, so a metastore created while the default was `none` stays on `none` — the runtime warns at startup when it finds one. To move it to `incremental`, stop the runtime, run `PRAGMA auto_vacuum = INCREMENTAL; VACUUM;` against the metastore file, and restart: the pragma alone is a no-op on a file created with `auto_vacuum = none`, and a bare `VACUUM` keeps it on `none`. Switching between `full` and `incremental` needs no `VACUUM`. See the [SQLite `auto_vacuum` documentation](https://sqlite.org/pragma.html#pragma_auto_vacuum). | | `cayenne_metastore_incremental_vacuum_pages` | Freelist pages the background maintenance pass reclaims per tick when the metastore is in `incremental` `auto_vacuum` mode; ignored in every other mode. Defaults to `256`, which is 1 MiB at SQLite's 4 KiB default page size. Reclamation holds the write lock while it relocates pages, so the cap is what keeps each pause short; raise it to drain a large freelist faster at the cost of longer write-lock holds, or set `0` to stop reclaiming without changing the database's `auto_vacuum` mode. | ```yaml diff --git a/website/versioned_docs/version-2.0.x/components/data-accelerators/cayenne/index.md b/website/versioned_docs/version-2.0.x/components/data-accelerators/cayenne/index.md index b16e17f49..d33826ae9 100644 --- a/website/versioned_docs/version-2.0.x/components/data-accelerators/cayenne/index.md +++ b/website/versioned_docs/version-2.0.x/components/data-accelerators/cayenne/index.md @@ -127,7 +127,7 @@ Set once under the top-level `runtime.params` and applied to every Cayenne-accel | `cayenne_metastore_mmap_mb` | SQLite metastore memory-mapped I/O size in megabytes. Defaults to `1024` (1 GiB). | | `cayenne_metastore_busy_timeout_ms` | SQLite metastore `busy_timeout` in milliseconds — how long a blocked connection waits for a lock before erroring. Defaults to `30000`. | | `cayenne_metastore_wal_autocheckpoint_pages` | SQLite metastore WAL auto-checkpoint threshold in pages; the WAL is checkpointed automatically once it grows past this many pages. Defaults to `10000`. | -| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation: changing it on an existing metastore takes `PRAGMA auto_vacuum = ` followed by a full `VACUUM` — the pragma alone is a no-op there, and a bare `VACUUM` keeps the file on the mode it already has. Defaults to `none`. | +| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation. Switching an existing metastore between `full` and `incremental` takes effect from `PRAGMA auto_vacuum = ` on its own; moving it to or from `none` needs a full `VACUUM` after the pragma, because the pragma alone is a no-op in that direction and a bare `VACUUM` keeps the file on the mode it already has. See the [SQLite `auto_vacuum` documentation](https://sqlite.org/pragma.html#pragma_auto_vacuum). Defaults to `none`. | ```yaml runtime: diff --git a/website/versioned_docs/version-2.1.x/components/data-accelerators/cayenne/index.md b/website/versioned_docs/version-2.1.x/components/data-accelerators/cayenne/index.md index cfd69eadc..5ffd2264a 100644 --- a/website/versioned_docs/version-2.1.x/components/data-accelerators/cayenne/index.md +++ b/website/versioned_docs/version-2.1.x/components/data-accelerators/cayenne/index.md @@ -145,7 +145,7 @@ Set once under the top-level `runtime.params` and applied to every Cayenne-accel | `cayenne_metastore_busy_timeout_ms` | SQLite metastore `busy_timeout` in milliseconds — how long a blocked connection waits for a lock before erroring. Defaults to `30000`. | | `cayenne_metastore_wal_autocheckpoint_pages` | SQLite metastore WAL auto-checkpoint threshold in pages. `0` disables the inline auto-checkpoint so the WAL is drained off the hot commit path by a dedicated background checkpoint instead. Defaults to `0`. | | `cayenne_metastore_wal_truncate_threshold_mb` | WAL size in megabytes above which the background checkpoint escalates to a TRUNCATE checkpoint to reclaim file space. Defaults to `160`. | -| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation: changing it on an existing metastore takes `PRAGMA auto_vacuum = ` followed by a full `VACUUM` — the pragma alone is a no-op there, and a bare `VACUUM` keeps the file on the mode it already has. Defaults to `none`. | +| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation. Switching an existing metastore between `full` and `incremental` takes effect from `PRAGMA auto_vacuum = ` on its own; moving it to or from `none` needs a full `VACUUM` after the pragma, because the pragma alone is a no-op in that direction and a bare `VACUUM` keeps the file on the mode it already has. See the [SQLite `auto_vacuum` documentation](https://sqlite.org/pragma.html#pragma_auto_vacuum). Defaults to `none`. | ```yaml runtime: diff --git a/website/versioned_docs/version-2.2.x/components/data-accelerators/cayenne/index.md b/website/versioned_docs/version-2.2.x/components/data-accelerators/cayenne/index.md index 10795abfd..0d66086f3 100644 --- a/website/versioned_docs/version-2.2.x/components/data-accelerators/cayenne/index.md +++ b/website/versioned_docs/version-2.2.x/components/data-accelerators/cayenne/index.md @@ -179,7 +179,7 @@ A global `cayenne_goal_*` setpoint steers only the datasets that run the closed | `cayenne_metastore_busy_timeout_ms` | SQLite metastore `busy_timeout` in milliseconds — how long a blocked connection waits for a lock before erroring. Defaults to `30000`. | | `cayenne_metastore_wal_autocheckpoint_pages` | SQLite metastore WAL auto-checkpoint threshold in pages. `0` disables the inline auto-checkpoint so the WAL is drained off the hot commit path by a dedicated background checkpoint instead. Defaults to `0`. | | `cayenne_metastore_wal_truncate_threshold_mb` | WAL size in megabytes above which the background checkpoint escalates to a TRUNCATE checkpoint to reclaim file space. Defaults to `160`. | -| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation: changing it on an existing metastore takes `PRAGMA auto_vacuum = ` followed by a full `VACUUM` — the pragma alone is a no-op there, and a bare `VACUUM` keeps the file on the mode it already has. Defaults to `none`. Under `incremental`, freed pages are marked reclaimable and reclaimed in bounded batches by the background maintenance pass — see `cayenne_metastore_incremental_vacuum_pages`. An unrecognized value logs a warning and falls back to `none`. | +| `cayenne_metastore_auto_vacuum` | SQLite metastore `auto_vacuum` mode: `none`, `incremental`, or `full`. SQLite fixes the mode at file creation. Switching an existing metastore between `full` and `incremental` takes effect from `PRAGMA auto_vacuum = ` on its own; moving it to or from `none` needs a full `VACUUM` after the pragma, because the pragma alone is a no-op in that direction and a bare `VACUUM` keeps the file on the mode it already has. See the [SQLite `auto_vacuum` documentation](https://sqlite.org/pragma.html#pragma_auto_vacuum). Defaults to `none`. Under `incremental`, freed pages are marked reclaimable and reclaimed in bounded batches by the background maintenance pass — see `cayenne_metastore_incremental_vacuum_pages`. An unrecognized value logs a warning and falls back to `none`. | | `cayenne_metastore_incremental_vacuum_pages` | Freelist pages the background maintenance pass reclaims per tick when the metastore is in `incremental` `auto_vacuum` mode; ignored in every other mode. Defaults to `256`, which is 1 MiB at SQLite's 4 KiB default page size. Reclamation holds the write lock while it relocates pages, so the cap is what keeps each pause short; raise it to drain a large freelist faster at the cost of longer write-lock holds, or set `0` to stop reclaiming without changing the database's `auto_vacuum` mode. | ```yaml