logseq/docs/agent-guide/072-logseq-cli-graph-backup.md

Graph Backup Subcommands Implementation Plan

Goal: Add graph backup subcommands that create, list, restore, and remove backup graphs under backup/ using SQLite backup API for backup creation.

Architecture: Keep command parsing and human/json/edn output behavior in logseq-cli, and keep backup file generation inside db-worker-node through a new thread API that calls Node SQLite backup API. Architecture: Reuse the existing SQLite import path for restore to avoid introducing a second restore mechanism and to keep db bootstrap semantics aligned with current graph import --type sqlite behavior.

Tech Stack: ClojureScript, babashka.cli, logseq-cli command pipeline, db-worker-node /v1/invoke, Node node:sqlite, filesystem operations under CLI data dir.

Related: Builds on /Users/rcmerci/gh-repos/logseq/docs/agent-guide/006-logseq-cli-import-export.md. Related: Builds on /Users/rcmerci/gh-repos/logseq/docs/agent-guide/037-db-worker-node-node-sqlite.md. Related: Relates to /Users/rcmerci/gh-repos/logseq/docs/agent-guide/060-cli-graph-list-legacy-graph-dir-rename-command.md and /Users/rcmerci/gh-repos/logseq/docs/agent-guide/061-graph-dir-space-preserve-canonical.md.

Problem statement

logseq-cli currently supports graph export and graph import, but it has no first-class backup lifecycle for graph snapshots.

Current SQLite export reads db.sqlite bytes through :thread-api/export-db-base64 after wal_checkpoint, which is functional but does not use SQLite backup API.

We need backup-specific commands that treat backups as managed graph-like artifacts stored under backup/ and independent from normal graph directories.

The requested command set is graph backup list, graph backup create, graph backup restore --src <backup-name> --dst <new-graph-name>, and graph backup remove.

The scope explicitly covers only db.sqlite and excludes search-db.sqlite and client-ops-db.sqlite.

Requested command contract

Command	Behavior	Notes
logseq graph backup list	List all backup graphs under <data-dir>/backup/.	Returns metadata including name, created-at, and size-bytes.
logseq graph backup create [--name <name>]	Create a backup graph for --graph <name> or current graph from config.	Must use SQLite backup API for db.sqlite.
logseq graph backup restore --src <backup-name> --dst <new-graph-name>	Restore one backup graph into a new normal graph.	Destination must not already exist and must fail if it exists.
logseq graph backup remove --src <backup-name>	Remove one backup graph directory.	Physical delete of backup entry.

graph backup remove uses --src to align with restore semantics.

Current baseline and constraints

CLI graph subcommands are registered in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs and routed in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs.

Graph list currently scans graph directories directly under data-dir using /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs.

Node runtime storage list in /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs also scans top-level directories under data-dir.

If we add a top-level backup/ directory, both scanners must explicitly ignore it to prevent backup from appearing as a normal graph.

Worker-side SQLite import/export thread APIs already exist in /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs and are exercised in /Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs.

Human formatting for graph commands is centralized in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs.

Non-sync CLI e2e coverage is now shell-driven in /Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn and /Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn.

Target architecture

logseq graph backup create
  -> logseq.cli.command.graph/execute-graph-backup-create
    -> ensure db-worker-node for source repo
      -> /v1/invoke :thread-api/backup-db-sqlite [repo dst-db-path]
        -> node:sqlite backup API
          -> <data-dir>/backup/<encoded-backup-name>/db.sqlite

logseq graph backup restore --src A --dst B
  -> resolve <data-dir>/backup/<encoded-A>/db.sqlite
    -> reuse sqlite import flow into repo logseq_db_B
      -> graph becomes normal top-level graph directory

Backup listing and removal stay CLI-side filesystem operations and do not require new worker endpoints.

Backup creation is the only operation that must call SQLite backup API.

Storage and naming model

Backup root path will be <resolved-data-dir>/backup.

Each backup graph will be stored as <resolved-data-dir>/backup/<encoded-backup-name>/db.sqlite.

Backup name is user-facing and decoded with existing graph-dir encode/decode helpers for consistency with current graph directory naming behavior.

graph backup create will auto-generate backup name as <source-graph>-<UTC-timestamp>.

When --name <name> is provided, backup name format becomes <source-graph>-<name>-<UTC-timestamp>.

A short suffix is appended on collision.

graph backup list returns decoded backup names with metadata including created-at and size-bytes derived from filesystem stat.

No search db or client-ops db files are copied into backup entries.

Testing Plan

I will follow @test-driven-development and implement this feature with failing tests first.

I will start by adding failing CLI parse/build tests for all new commands and required options.

I will add failing worker-side tests that prove backup creation returns a valid sqlite file that can be imported into another repo.

I will add failing graph-directory scanner tests to ensure backup/ is ignored by normal graph listing.

I will add failing formatting tests for new human output messages and list rendering.

I will add failing CLI e2e cases that run create -> list -> restore -> remove against a temp data dir.

I will update CLI docs after behavior is stabilized and tests pass.

NOTE: I will write all tests before I add any implementation behavior.

Implementation plan

Phase 1: Add failing tests for command parsing and action building.

1. Add parse tests in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs for graph backup list, graph backup create, graph backup restore, and graph backup remove.

2. Add parse tests asserting graph backup create --name <name> is accepted and passed through as optional naming input.

3. Add parse tests asserting backup name generation follows <graph>-<name>-<timestamp> when --name is provided.

4. Add parse tests asserting graph backup restore requires --src and --dst.

5. Add parse tests asserting graph backup remove requires --src.

6. Add build-action tests for each new command and assert resulting action :type values.

7. Add build-action tests asserting graph backup create resolves source repo from --graph or current config graph and fails with :missing-repo when no graph is available.

Phase 2: Add failing tests for command execution and formatting.

8. Add execution unit tests in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs for backup list/create/restore/remove with mocked filesystem and transport calls.

9. Add tests that backup create invokes new worker method :thread-api/backup-db-sqlite exactly once with source repo and destination sqlite path.

10. Add tests that backup restore rejects missing source backup and rejects existing destination graph.

11. Add tests that backup restore reuses sqlite import flow semantics and returns new-graph? true style success metadata.

12. Add formatting tests in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs for human output of backup list/create/restore/remove.

13. Add formatting tests for backup list metadata rendering (name, created-at, size-bytes) in human/json/edn output.

Phase 3: Add failing tests for graph scanners and worker backup API.

14. Extend /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs so list-graph-items ignores top-level backup directory.

15. Add platform node tests in /Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/platform_node_test.cljs for backup API wrapper behavior.

16. Add daemon-level test in /Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs that calls thread-api/backup-db-sqlite and verifies produced sqlite file can seed another repo via existing import API.

17. Add daemon-level lock test that backup API is treated as a write operation and fails for stale/non-owner lock states.

Phase 4: Implement worker-side backup API.

18. Add a new thread API in /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs named :thread-api/backup-db-sqlite.

19. Implement thread API behavior to backup only main db connection for repo and return deterministic metadata { :path <dst> }.

20. Extend Node sqlite wrapper in /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs to expose backup capability from DatabaseSync through wrapped connection object.

21. Guard destination writes with existing write-guard-fn semantics so lock ownership is enforced for backup generation.

22. Ensure parent directory creation for destination file is handled before backup call.

23. Add new worker method to write-method allowlist in /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs.

24. Keep route protocol unchanged by continuing to use /v1/invoke.

Phase 5: Implement CLI backup storage helpers and command handlers.

25. Add backup option specs and command entries in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs, including optional --name for create and --src for remove.

26. Add action builders for :graph-backup-list, :graph-backup-create, :graph-backup-restore, and :graph-backup-remove.

27. Add execution functions in graph.cljs for list/create/restore/remove with focused responsibilities.

28. Implement backup root and backup item helper functions using resolved CLI data dir and graph-dir encoding/decoding.

29. Implement backup create execution to generate backup name from <graph>-<timestamp> or <graph>-<name>-<timestamp>, create target dir, and call transport/invoke with :thread-api/backup-db-sqlite.

30. Implement backup restore execution to map --src to backup sqlite path and then reuse sqlite import workflow for destination repo.

31. Implement backup remove execution to recursively remove target backup directory.

32. Add validation and dispatch wiring in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs for new commands and required flags.

33. Add context keys (:src, :dst, :backup-name) in execute result metadata for formatter use.

Phase 6: Keep normal graph listing behavior correct.

34. Update /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs directory classification to ignore backup root.

35. Update /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs list-graphs scanner to ignore backup root.

36. Verify that graph list and thread-api/list-db do not show backup as a graph.

Phase 7: Update output, completion, docs, and e2e coverage.

37. Add formatter branches in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs for backup commands with concise human lines and metadata rendering for list output.

38. Update completion tests in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs so graph group includes backup subcommands and restore/remove flags.

39. Update /Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn to include new graph backup commands and options (--name, --src, --dst).

40. Add e2e cases in /Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn for create/list/restore/remove flows, including one create case with --name.

41. Update /Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md command list and examples for graph backup commands.

42. Add one doc note that backup commands copy only db.sqlite and intentionally skip search/client-ops sqlite files.

File-by-file change map

File	Planned change
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs	Add backup command entries, option specs, action builders, filesystem helper functions, and execute logic for list/create/restore/remove.
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs	Add parser validation for backup flags, build-action routing, execute dispatch, and context key propagation.
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs	Add human output formatting for backup list/create/restore/remove and ensure machine outputs remain stable.
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs	Ignore top-level backup directory when listing normal graphs.
/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs	Add :thread-api/backup-db-sqlite implementation for main sqlite db backup generation.
/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs	Expose Node sqlite backup capability and ensure list-graphs ignores backup root.
/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs	Register backup API as write method for lock-owner enforcement.
/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs	Add parse/build/execute tests for backup commands and required option errors.
/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs	Add unit tests for backup command execution behaviors and transport invocation contract.
/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs	Add human/json/edn formatting tests for backup command outputs.
/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs	Add scanner tests proving backup root is excluded from graph list.
/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/platform_node_test.cljs	Add unit tests for backup API wrapper behavior and destination file creation.
/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs	Add integration test covering backup API correctness and lock enforcement behavior.
/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs	Assert completion includes graph backup subcommands and options.
/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn	Include graph backup command and option coverage inventory entries.
/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn	Add end-to-end graph backup lifecycle cases.
/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md	Document backup commands and db.sqlite-only scope note.

Edge cases and behavior guarantees

Backup names with spaces and slashes are supported through existing graph-dir encode/decode helpers.

Optional --name values with spaces and symbols are supported and encoded through the same helpers.

Backup creation must fail clearly when source graph does not exist or backup target path cannot be created.

Backup restore must fail clearly when source backup does not exist.

Backup restore must fail clearly when destination graph already exists.

Backup remove must fail clearly when source backup does not exist.

graph list must not include backup entries.

graph backup list metadata fields (created-at, size-bytes) must remain present and stable even when sorting order changes.

Backup API must preserve binary integrity for large sqlite files and not truncate output.

Backup operations must respect lock ownership semantics already enforced for write methods.

Verification commands

bb dev:test -v logseq.cli.command.graph-test
bb dev:test -v logseq.cli.commands-test
bb dev:test -v logseq.cli.format-test
bb dev:test -v logseq.cli.server-test
bb dev:test -v frontend.worker.platform-node-test
bb dev:test -v frontend.worker.db-worker-node-test/db-worker-node-import-db-base64
bb dev:test -v frontend.worker.db-worker-node-test/db-worker-node-write-mutation-fails-for-non-owner-pid
bb -f cli-e2e/bb.edn test --skip-build
bb dev:lint-and-test

Expected results are passing tests for parser behavior, backup API correctness, lock safety, graph-list isolation, and CLI end-to-end backup lifecycle.

Testing Details

I will add tests that validate end-user behavior of backup command parsing, execution, output, and restore correctness.

I will assert backup file validity by actually importing the generated sqlite backup into a new graph and querying known content.

I will assert list isolation behavior by verifying backup root never appears in normal graph listings.

I will keep lock-related assertions behavior-driven by invoking through daemon HTTP APIs rather than testing private internals.

Implementation Details

• Add graph backup command entries under existing graph command group instead of creating a new top-level command.
• Use existing global --graph resolution as backup source selector for graph backup create.
• Introduce optional --name for create, --src and --dst for restore, and --src for remove.
• Store backups under <data-dir>/backup/<encoded-backup-name>/db.sqlite.
• Generate backup names as <graph>-<timestamp> by default and <graph>-<name>-<timestamp> when --name is provided, with collision suffix when needed.
• Use a new worker thread API to call Node SQLite backup API for backup creation.
• Reuse existing sqlite import flow for restore to keep db bootstrap behavior consistent.
• Mark worker backup method as write operation so lock ownership checks remain enforced.
• Ignore top-level backup directory in both CLI and node platform graph scanners.
• Return backup list metadata including created-at and size-bytes in machine output and render it in human output.
• Update completion, docs, and e2e specs together so command contract is synchronized.

Question

Do we reserve the top-level graph name backup going forward, or do we need a migration strategy for users who already have a normal graph named backup in the same data dir?

---