Database schemas

​

Database layout

​

Versioning contract

• PRAGMA user_version is the SQLite schema version.
• The primary schema_meta row records role, agent_id, schema_version, and app_version. app_version is the OpenClaw build that last wrote the schema metadata.

​

Agent schema history

​

State schema history

​

Integrity checks

​

Troubleshooting

​

Why you cannot go back after updating to 2026.7.2

1. Restore a backup taken before the update. Create and verify backups before major updates.
2. Run the older build against a separate state directory (OPENCLAW_STATE_DIR). It starts fresh; your migrated data stays untouched for when you return to the newer build.
3. Follow the manual downgrade procedure below. It is unsupported and risks data loss without a verified backup.

​

The Gateway refuses to start with a newer schema version error

​

A database is quarantined after integrity verification failed

​

Downgrades are unsupported

1. Read the target release’s schema and migrations.
2. In one transaction, drop every table, index, trigger, and column introduced after the target version.
3. Set PRAGMA user_version and schema_meta.schema_version to the target version.
4. Run the target release’s full database verification before starting the Gateway.

​

Example: agent schema 11 to 9

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;