Skip to content

Commit 409d541

Browse files
giodl73-repogiodl73-repo
committed
Nest SQLite snapshots under backup
1 parent ece661b commit 409d541

9 files changed

Lines changed: 322 additions & 340 deletions

‎docs/cli/backup.md‎

Lines changed: 90 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
2-
summary: "CLI reference for `openclaw backup` (create local backup archives)"
2+
summary: "CLI reference for `openclaw backup` (archives and SQLite-safe artifacts)"
33
read_when:
44
- You want a first-class backup archive for local OpenClaw state
5+
- You need a SQLite-safe artifact for one OpenClaw database
56
- You want to preview which paths would be included before reset or uninstall
67
title: "Backup"
78
---
@@ -18,6 +19,11 @@ openclaw backup create --verify
1819
openclaw backup create --no-include-workspace
1920
openclaw backup create --only-config
2021
openclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gz
22+
openclaw backup sqlite snapshot create --target global --repository ./snapshots
23+
openclaw backup sqlite snapshot create --agent main --repository ./snapshots
24+
openclaw backup sqlite snapshot list --repository ./snapshots
25+
openclaw backup sqlite snapshot verify ./snapshots/<snapshot-id>
26+
openclaw backup sqlite snapshot restore ./snapshots/<snapshot-id> --target ./restore/openclaw.sqlite
2127
```
2228

2329
## Notes
@@ -27,7 +33,89 @@ openclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gz
2733
- Existing archive files are never overwritten. Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
2834
- `openclaw backup verify <archive>` checks that the archive contains exactly one root manifest, rejects traversal-style archive paths, and confirms every manifest-declared payload exists in the tarball. `openclaw backup create --verify` runs that validation immediately after writing the archive.
2935
- `openclaw backup create --only-config` backs up just the active JSON config file.
30-
- If you only need a SQLite-safe sync artifact for one OpenClaw database, use [`openclaw snapshot`](/cli/snapshot). Backup is for broad recovery archives.
36+
- If you only need a SQLite-safe sync artifact for one OpenClaw database, use `openclaw backup sqlite snapshot`. `backup create` is for broad recovery archives.
37+
38+
## SQLite snapshot artifacts
39+
40+
Use `openclaw backup sqlite snapshot` when you need a syncable artifact for one
41+
SQLite database. A snapshot repository stores verified snapshot directories
42+
containing `manifest.json` and `database.sqlite`, so a host, container, object
43+
storage sync, or backup system can copy those files instead of copying a hot
44+
SQLite database.
45+
46+
Use `openclaw backup create` when you need a broader local recovery archive for
47+
OpenClaw state, config, auth profiles, credentials, sessions, and optional
48+
workspaces. Backup archives may contain SQLite-safe database copies, but their
49+
output and restore model are archive-level, not a per-database snapshot
50+
repository.
51+
52+
### What to sync
53+
54+
Sync the snapshot directory created under the repository. A snapshot directory
55+
contains:
56+
57+
- `manifest.json`
58+
- `database.sqlite`
59+
60+
Do not sync live SQLite runtime files as the portability artifact:
61+
62+
- `openclaw.sqlite`
63+
- `openclaw.sqlite-wal`
64+
- `openclaw.sqlite-shm`
65+
- `openclaw-agent.sqlite`
66+
- `openclaw-agent.sqlite-wal`
67+
- `openclaw-agent.sqlite-shm`
68+
69+
Those files are hot runtime state. `openclaw backup sqlite snapshot create`
70+
reads the live database and writes a compact, verified SQLite artifact that can
71+
be copied by a host, container, object storage sync, or backup system.
72+
73+
SQLite snapshot artifacts are still sensitive state. Global and per-agent
74+
artifacts can include auth profile records, session state, plugin state, and
75+
other credentials-adjacent data from the source SQLite database. Protect
76+
snapshot repositories with the same access controls, encryption, retention
77+
policy, and upload destination restrictions you use for OpenClaw backups and
78+
live state.
79+
80+
### Named SQLite targets
81+
82+
Use named targets when snapshotting OpenClaw-owned SQLite state:
83+
84+
| Command | Source |
85+
| --------------------------------------------------------------------------- | ---------------------------------------------- |
86+
| `openclaw backup sqlite snapshot create --target global --repository <dir>` | Shared control-plane state database |
87+
| `openclaw backup sqlite snapshot create --agent <id> --repository <dir>` | Per-agent database for the normalized agent id |
88+
89+
`--db <path>` remains available for explicit SQLite files and advanced scripts.
90+
Choose only one source selector: `--db`, `--target`, or `--agent`.
91+
92+
Hosted runtimes should ask OpenClaw to materialize the named target instead of
93+
copying private SQLite paths. Hosts can sync only completed snapshot artifacts
94+
from the repository.
95+
96+
### Restore a SQLite artifact
97+
98+
Restore from the copied snapshot directory, not from the live source database
99+
files:
100+
101+
```bash
102+
openclaw backup sqlite snapshot verify ./synced/snapshot
103+
openclaw backup sqlite snapshot restore ./synced/snapshot --target ./hydrated/openclaw.sqlite
104+
```
105+
106+
Restore verifies the manifest, artifact hash, and SQLite integrity before
107+
copying the artifact to the target path. The target SQLite file must not already
108+
exist; stale `-wal`, `-shm`, and `-journal` sidecars at the target path are
109+
removed after the restore copy.
110+
111+
### SQLite snapshot notes
112+
113+
- Snapshot creation uses SQLite `VACUUM INTO`, so deleted-page remnants are not
114+
carried into the artifact.
115+
- Snapshot repositories are local directories. Uploading or scheduling them is
116+
intentionally left to the operator or a future integration.
117+
- This command does not add WAL bundle deltas, leases, failover automation, or
118+
restore-on-boot behavior.
31119

32120
## What gets backed up
33121

‎docs/cli/snapshot.md‎

Lines changed: 0 additions & 106 deletions
This file was deleted.

‎docs/docs.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1725,7 +1725,6 @@
17251725
"group": "Gateway and service",
17261726
"pages": [
17271727
"cli/backup",
1728-
"cli/snapshot",
17291728
"cli/crestodian",
17301729
"cli/daemon",
17311730
"cli/doctor",

‎src/cli/program/command-registry-core.ts‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -82,11 +82,6 @@ const coreEntrySpecs: readonly CommandGroupDescriptorSpec<
8282
loadModule: () => import("./register.backup.js"),
8383
exportName: "registerBackupCommand",
8484
},
85-
{
86-
commandNames: ["snapshot"],
87-
loadModule: () => import("./register.snapshot.js"),
88-
exportName: "registerSnapshotCommand",
89-
},
9085
{
9186
commandNames: ["migrate"],
9287
loadModule: () => import("./register.migrate.js"),

‎src/cli/program/core-command-descriptors.ts‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,7 @@ const coreCliCommandCatalog = defineCommandDescriptorCatalog([
3434
},
3535
{
3636
name: "backup",
37-
description: "Create and verify local backup archives for OpenClaw state",
38-
hasSubcommands: true,
39-
},
40-
{
41-
name: "snapshot",
42-
description: "Create, verify, list, and restore SQLite snapshots",
37+
description: "Create archives and SQLite-safe backup artifacts for OpenClaw state",
4338
hasSubcommands: true,
4439
},
4540
{

0 commit comments

Comments
 (0)