opschain admin database vacuum
Included from Basic tier
Runs space maintenance now — a POST to /api/admin/database/vacuum. On
PostgreSQL that is a per-table VACUUM (ANALYZE), reclaiming dead tuples and
refreshing statistics in one pass; on SQLite, PRAGMA optimize. By default
the run covers the configured churn set (the tables the scheduled weekly
vacuum window maintains, from config.yaml's database.maintenance block);
--table narrows it. The command prints the server's JSON response
describing the run.
This is the on-demand form of the scheduled vacuum window — reach for it
when admin database status shows a table whose DEAD count has grown large
and the next window is too far away.
Flags
| Flag | Meaning |
|---|---|
--server <url> | Server base URL (default: the active context / OPSCHAIN_SERVER). |
--auth-token <token> | Admin bearer token override (default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login). |
--table <name> | Limit the run to this table (repeatable; default: the configured churn set). |
Output is the response document itself — JSON, or YAML under -o yaml.
Exit codes
| Code | Meaning |
|---|---|
| 0 | The run was accepted and reported. |
| 1 | Request failed, non-2xx response, or the token was rejected. |
| 2 | Usage error — no server or no credential resolvable. |
Named errors
a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>'— exit 2.this command needs a login or an admin token — run 'opschain login', pass --auth-token, set OPSCHAIN_ADMIN_TOKEN, or store one with 'opschain admin login'— exit 2.the server rejected the credential — run 'opschain login' again, or check the admin token— HTTP 401 (exit 1).
Examples
opschain admin database vacuum
opschain admin database vacuum --table events
See also
opschain docs cli/admin-database-status— the dead-tuple counts that justify a run, and the run record afterwards.opschain docs cli/admin-database-analyze— statistics only, no space reclamation.