Skip to content

refactor(tools): rewrite qbit-ctl as a dependency-free Python console - #58

Merged
SeanChangX merged 2 commits into
mainfrom
refactor/qbit-ctl-tui
Nov 11, 2026
Merged

SeanChangX merged 2 commits into
mainfrom
refactor/qbit-ctl-tui

Conversation

@SeanChangX

Copy link
Copy Markdown
Owner

Summary

Rewrites tools/qbit-ctl as a single Python 3.10+ file that uses only the standard library (curses). The bash/whiptail version broke when newer sqlite3 rejected .mode tab, and had data-safety gaps (hot tar backups of a WAL database, restores that extracted over the old files or ran with the backend up, partial library deletes, columns shifting on NULL or |).

All data access now runs inside the backend image (node + better-sqlite3): docker exec while the backend runs, a throwaway container when it is stopped. No network access or apk add is needed, and the SQLite version always matches the backend.

What changes

  • Backups: VACUUM INTO snapshot taken before files/ is copied, integrity-checked, written atomically. Consistent while the backend keeps serving. Archive name and layout are unchanged (qbit-data-backup-<ts>.tar.gz with qbit.db, secrets.json, files/).
  • Restore: validates the archive in a container without the live volume, stops the backend, saves a safety backup, empties the volume, extracts, waits for the health check. A failed extract puts the safety backup back. Ctrl-C / SIGHUP cannot interrupt it. Requires typing restore to confirm.
  • Library delete: one transaction; restarting the backend to refresh its in-memory cache is offered, not forced.
  • Console: Overview, Backups, Database (11 read-only queries), Library, Volume tabs. Commands for scripts and cron: status, backup, backups.
  • Backup directory: --dir > $QBIT_CTL_BACKUP_DIR > [backups] dir in $XDG_CONFIG_HOME/qbit-ctl/config.ini (set or reset from the console) > ~/qbit_backups.
  • CI: new Tools (qbit-ctl) job, run when tools/ or web/backend/src/db.ts changes; included in the required ci check.

Testing

  • 23 unit tests on Python 3.10 and 3.12, including every console query run against the schema in web/backend/src/db.ts.
  • End to end against a local backend container with fake data: all queries, backup, archive validation (corrupt archive rejected), library delete, restore round trip, restore rollback on a simulated extract failure, SIGHUP during restore, restart with health check, shell, NO_COLOR, small and very wide terminals.
  • Two independent reviews; all findings fixed.

Deployment impact

None for the running services: only the operator script changes. Update the checkout on the server with git pull --ff-only; no rebuild or restart.

The bash/whiptail version installed sqlite3 with apk on every query, which
broke when newer sqlite3 rejected `.mode tab`, and had data-safety gaps:
hot tar backups of a WAL database, restores that extracted over the old
files (or ran with the backend up), partial library deletes, and columns
that shifted on NULLs or `|`.

qbit-ctl is now a single Python 3.10+ file using only the standard library
(curses). All data access runs inside the backend image (node +
better-sqlite3), via `docker exec` or a throwaway container when the
backend is stopped, so no network or extra packages are needed.

- Backups: VACUUM INTO snapshot taken before files/ is copied,
  integrity-checked, written atomically; consistent while the backend runs.
- Restore: validate the archive in a container without the live volume,
  stop the backend, save a safety backup, empty the volume, extract, wait
  for the health check. A failed extract puts the safety backup back.
  Ctrl-C and SIGHUP cannot interrupt it.
- Library delete runs in one transaction; restarting the backend to
  refresh its cache is offered, not forced.
- Console tabs: overview, backups, database (11 read-only queries),
  library, volume; commands `status`, `backup` and `backups` for scripts.
- Backup directory: --dir, $QBIT_CTL_BACKUP_DIR, [backups] dir in
  $XDG_CONFIG_HOME/qbit-ctl/config.ini (set or reset from the console),
  then ~/qbit_backups. The archive name and layout are unchanged.
- Unit tests run every query against the schema in web/backend/src/db.ts.
@SeanChangX
SeanChangX merged commit 86be48b into main Nov 11, 2026
8 checks passed
@SeanChangX
SeanChangX deleted the refactor/qbit-ctl-tui branch November 11, 2026 11:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant