openclaw/docs/reference/database-schemas.md

summary, read_when, title

summary	read_when	title
OpenClaw SQLite database locations, schema versions, integrity checks, and downgrade recovery	Diagnosing a newer database schema error Checking database compatibility before an update or downgrade Proposing a SQLite or persistent-store change Preparing storage operations for another database backend Recovering a database for an older OpenClaw release	Database schemas

OpenClaw stores control-plane state in the shared state 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.

Schema-version, integrity, canonical-index, and table-existence checks belong to open/admission and the migration owner after migrations; runtime paths must carry admitted schema facts with the handle, never re-query them, and use fresh PRAGMA data_version probes to observe foreign commits on the next unpinned read while preserving active SQLite snapshots. Existing per-call checks are legacy and must be migrated when touched.

Two mechanisms back that contract. CI runs scripts/check-native-state-schema-version.mjs, which fails the build when the Swift and TypeScript state-database contracts declare different schema versions. openclaw doctor --fix owns file-to-SQLite migrations and records a receipt for each one in the shared migration_runs and migration_sources tables.

Execution step receipts are separate from these persisted import receipts. A step blocked by an earlier refusal includes optional originatingRefusal fields stepId, code, and message naming the first failure. See legacy state migration for how to resolve it.

This page is an index. The reference is documented on focused pages, one per reader job. Open the page that matches your task and stay there.

Page	Read it when
Database layout	The two database roles, their on-disk paths, and the tables behind individual features.
Versioning contract	How schema versions are recorded, when a bump is required, and how updaters cross one.
Per-person and companion storage	Personal GitHub connections, personal model accounts, and Apple companion delivery journals.
Storage changes and release preflight	Preparing for another backend, the material-change review checkpoint, and openclaw database preflight.
Database access in workers	Moving runtime reads and writes off the Gateway main thread while preserving their owners.
Worker migration inventory	Reproducing the synchronous-access inventory and choosing the next migration.
Agent schema history	Per-agent database schema versions, their changes, and their first releases.
State schema history	Shared state database schema versions, their changes, and their first releases.
Integrity, troubleshooting, and recovery	Integrity checks, common database errors, and the supported downgrade recovery path.

Related

• Backups — archives, per-database snapshots, scheduling, and offsite copies for the databases described here
• Updating — updating safely, including the verified backup to take before a schema bump, and the rollback strategy
• Doctor — the repair and migration tool that fixes stale config/state and reports health problems
• openclaw doctor — CLI reference for the command that runs those migrations
• openclaw update — CLI reference for the updater that preflights schema support

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /reference/database-schemas#schema-bumps-and-older-updaters still resolves. Each entry points at the page that now holds the content.

• Database layout
• Plugin state listing index
• Mentions Inbox
• ACP replay accounting
• Meeting transcript tables
• meeting_transcript_sessions
• meeting_transcript_utterances
• meeting_transcript_summaries
• Update run ledger
• Cloud repository workspaces
• Versioning contract
• Schema bumps and older updaters
• Profile-owned skill library
• Personal GitHub connections and publication
• Personal model accounts
• Apple companion delivery journals
• Preparing for another database backend
• Keep operations at the owning store
• Preserve the data and concurrency contracts
• Keep engine-specific capabilities owned
• Review checkpoint for material changes
• Preflight a target release
  • Preflight an explicit agent copy
• Agent schema history
• Creator namespace migration
• Participant identity migration
• State schema history
• State schema 16
• State schema 15
• State schema 13
• State schema 11
• State schema 9
• Integrity checks
• Troubleshooting
• Why you cannot go back after updating to 2026.7.2
• The Gateway refuses to start with a newer schema version error
• A database is quarantined after integrity verification failed
• Downgrades are unsupported
• Example: state schema 13 to 12
• Example: state schema 12 to 11
• Example: state schema 11 to 10
• Example: state schema 10 to 9
• Example: state schema 9 to 8
• Example: state schema 7 to 6
• Example: agent schema 17 to 16
• Downgrade recovery