dbterm guide

1. Start in 60 seconds

Install, connect, run SQL, then iterate in panel-focused flow.

curl -fsSL https://raw.githubusercontent.com/shreyam1008/dbterm/main/install.sh | bash

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/shreyam1008/dbterm/main/install.ps1 | iex"

2. Understand the workspace

dbterm is optimized around panel focus and keyboard flow.

Scroll horizontally to inspect every column.

3. Essential shortcuts

Use these to avoid context switching and keep query loops fast.

Scroll horizontally to inspect every shortcut and action.

Use Esc and Backspace to back out safely from most views if you lose focus.

4. Instant backup, scheduled agent, guarded restore

One backup engine serves the TUI, CLI, and background agent. See the focused Backup Center guide for the complete operator model.

dbterm backup keygen
dbterm backup service install
dbterm backup service status --all
dbterm backup logs --lines 200
dbterm backup inspect --identity ./age-identity.txt ./prod.dump.zst.age
dbterm backup restore --connection production --identity ./age-identity.txt --yes ./prod.dump.zst.age

Scheduled destinations can be absolute local/mounted folders or rclone://remote/path locations. Configure rclone under the backup agent’s OS account. PostgreSQL/MySQL require their official clients; SQLite SQL restore requires sqlite3. Restore supports PostgreSQL, MySQL/MariaDB, and local SQLite. Merge is the restore default; clean restore is explicit and destructive.

Retention can combine newest-count, maximum-age, and total-size ceilings. Backup Center previews capacity and can apply the policy immediately; cleanup is restricted to verified artifacts recorded for that exact job, and always preserves its newest successful backup.

Per-job email can report failures, successes, both, or neither. Gmail defaults to STARTTLS on port 587; custom SMTP and implicit TLS are available. Test delivery before relying on it, and protect the locally stored app password.

Desktop scope is the no-admin default. Server scope runs at machine boot without an interactive login and requires elevation plus explicit existing config, state, and log paths. Runtime start/stop and startup enable/disable are deliberately separate controls.

Run dbterm backup paths for exact resolved paths. Raw dumps are wrapped in private state staging before the finished artifact is published to your destination, so private state needs room for one uncompressed dump. The live view shows real phase, byte growth, elapsed time, rate, and ETA where a meaningful total exists. Uninstalling only the agent never removes completed artifacts.

Restore only trusted files: dbterm rechecks content, checksum, engine, and client-side commands, but valid SQL can still perform any server-side action allowed to the selected database account. Turso exports use one source transaction and reject virtual/FTS schemas; D1 uses Cloudflare's native export API, which can briefly make that database unavailable.

Inspection unwraps at most three layers. Every decoded gzip, zstd, ZIP, or age layer has a 1 GiB default cap and uses private OS temporary storage; raise it with the TUI’s Max Decoded GiB field or --max-decoded-gib N, with enough temporary disk space available.

backup keygen defaults the private identity into dbterm config. For recovery safety, --uninstall --purge refuses to remove a private age identity or backup-like file it discovers there; move the key somewhere safe or delete it explicitly before retrying.

5. CLI maintenance reference

Use CLI mode for updates, diagnostics, and uninstall operations.

dbterm
dbterm --help
dbterm --version
dbterm --info
dbterm --update
dbterm --update X.Y.Z
dbterm --uninstall
dbterm --uninstall --purge
dbterm --uninstall --yes
dbterm backup --help
dbterm backup list
dbterm backup run <job>
dbterm backup inspect <file>
dbterm backup restore --connection <target> --yes <file>
dbterm backup service install
dbterm backup service status --all
dbterm backup service enable
dbterm backup prune --yes <job>
dbterm backup notify-test <job>
dbterm backup logs --lines 200
dbterm backup keygen
dbterm backup paths

Scroll horizontally to inspect every command and purpose.

6. Troubleshooting quick list

• Connection issues: run `dbterm --info`, verify host/port/credentials, then reconnect from dashboard.
• Query errors: open in-app cheatsheets with Alt+H to validate SQL syntax and DB-specific clauses.
• Permission errors removing a package-managed binary: use the owning installer/package manager or ask an administrator to remove only that binary; keep backup-agent and data operations in your normal user account.
• Large result sets: keep a safe on-screen preview and choose All matching in Alt+E; dbterm streams the full filtered export with progress and cancellation.
• Scheduled job did not run: open Backup Center → A or run `dbterm backup service status`; then verify the database client tool is available in the agent PATH.
• Server agent cannot install: use the exact elevated command shown by Backup Center and supply existing absolute config, state, and log directories accessible to the selected runtime user.
• Encrypted backup is locked: provide the matching age identity during inspection; jobs intentionally store only the public recipient.