a89f01abf4
* perf(sqlite): gate schema version before integrity scans and quarantine terminal open failures * feat(gateway): refuse incompatible database schemas at boot and verify integrity in the background * feat(update): refuse installing builds that cannot open the current databases * docs: add database schema reference with version history and downgrade guidance * test(update): tolerate optional runner options in git-mutation mocks * refactor(update): split npm package-target metadata out of update-check * chore: model verifier internals for knip and regenerate docs map * chore(i18n): resync stale iOS localization catalog * chore: allowlist read-only preflight and verifier raw SQLite access
9.3 KiB
summary, read_when, title
| summary | read_when | title | |||
|---|---|---|---|---|---|
| OpenClaw SQLite database locations, schema versions, integrity checks, and downgrade recovery |
|
Database schemas |
OpenClaw stores control-plane state in a global SQLite database and agent data in one SQLite database per agent. Schema migrations run forward when a database opens. Older OpenClaw builds refuse databases written by a newer schema.
Database layout
| Scope | Default path | Contents |
|---|---|---|
| Global control plane | ~/.openclaw/state/openclaw.sqlite |
Shared configuration state, registries, approvals, plugin state, and verification history |
| Per-agent data plane | ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite |
Sessions, transcripts, memory indexes, auth state, conversation state, and agent-scoped runtime state |
A few high-volume or lifecycle-specific features use dedicated SQLite stores, including the task registry and trajectory data.
Versioning contract
Each database records its schema in two places:
PRAGMA user_versionis the SQLite schema version.- The primary
schema_metarow recordsrole,agent_id,schema_version, andapp_version.app_versionis the OpenClaw build that last wrote the schema metadata.
OpenClaw applies forward-only migrations when it opens an older supported database. It refuses a database whose user_version is newer than the running build and reports a newer schema version error. The Gateway checks all registered databases before startup. openclaw update also refuses a package or source target whose declared schema support is older than an on-disk database. Target packages published before schema metadata was added cannot be preflighted.
Installing OpenClaw manually through npm bypasses the updater guard. Database open checks still refuse an incompatible build.
Agent schema history
| Version | Change | First release |
|---|---|---|
| 1 | Initial per-agent store (#88349) | v2026.5.30-beta.1, stable through v2026.7.1 |
| 2 | Memory index identity (#104449) | v2026.7.2-beta.1 |
| 4 | Sessions and transcripts moved into SQLite (#98236) | v2026.7.2-beta.1 |
| 5-6 | Terminal freshness and state lifecycle (#104859) | v2026.7.2-beta.1 |
| 7 | Per-entry lifecycle status projection (#106151) | v2026.7.2-beta.1 |
| 8 | Per-transcript session provenance (#106766) | v2026.7.2-beta.2 |
| 9 | STRICT tables (#108663) |
v2026.7.2-beta.2 |
| 10 | Materialized active transcript paths (#108851) | Unreleased |
| 11 | Leases, durable delivery, conversation addresses, and heartbeat outcomes (#109636, #95838, #109999) | Unreleased |
Version 3 was an unshipped development step folded into version 4.
State schema history
| Version | Change | First release |
|---|---|---|
| 1 | Initial shared state database | v2026.5.30-beta.1 |
| 2 | Metadata-only message audit events (#103903) | v2026.7.2-beta.1 |
| 3 | STRICT tables and schema-drift hardening (#108663) |
v2026.7.2-beta.2 |
Integrity checks
| When | Check |
|---|---|
| Every open | Validate the schema_meta table and primary metadata row |
| Before a pending migration | Run a full integrity, foreign-key, role, schema, and index scan |
| Gateway background verifier | Run the full scan about once daily and record results in the global database_verifications table |
| Doctor, backup verification, and compaction | Run the full scan before accepting or rewriting the database |
The Gateway preflight reads schema headers only. The background verifier owns the slower full scan for databases that do not need migration.
Downgrades are unsupported
Manual schema downgrades are for agents and operators who accept the risk. Create and verify a backup before editing any database. Stop the Gateway and every process that can open the database.
The general procedure is:
- Read the target release's schema and migrations.
- In one transaction, drop every table, index, trigger, and column introduced after the target version.
- Set
PRAGMA user_versionandschema_meta.schema_versionto the target version. - Run the target release's full database verification before starting the Gateway.
Example: agent schema 11 to 9
Schema 10 added the active transcript projection. Schema 11 added leases, durable delivery, conversation-address state, and heartbeat outcomes. QMD coordination uses rows in state_leases; there is no separate QMD table to preserve.
Run equivalent SQL against each affected per-agent database after inspecting the exact schema that wrote it:
BEGIN IMMEDIATE;
DROP TABLE IF EXISTS heartbeat_outcomes;
DROP TABLE IF EXISTS conversation_deliveries;
DROP TABLE IF EXISTS state_leases;
DROP TABLE IF EXISTS session_transcript_active_events;
ALTER TABLE session_transcript_index_state DROP COLUMN active_event_count;
ALTER TABLE session_transcript_index_state DROP COLUMN active_message_count;
ALTER TABLE conversations DROP COLUMN delivery_target;
PRAGMA user_version = 9;
UPDATE schema_meta
SET schema_version = 9,
updated_at = unixepoch('now') * 1000
WHERE meta_key = 'primary';
COMMIT;
This discards version 10-11 state, including in-flight delivery operations, leases, heartbeat outcomes, and the derived active transcript projection. A botched downgrade means restore from the verified backup.