DBOps User Manual

1. Getting started

DBOps is a browser-based control plane. It keeps its registry and snapshot metadata locally and connects to configured database targets for monitoring and backup operations.

Sign in with your username and password. Microsoft Authenticator is required only for accounts that have MFA enabled. For an MFA-enabled account, use the QR code or setup key provided by an administrator to configure Microsoft Authenticator, then enter the six-digit code when prompted.
Choose the active database using the target selector in Console, Overview, or Backups. In Console, you can also select a target from the carousel by clicking a card, dragging it, using its arrows, or focusing it and pressing the left/right arrow keys. The backup schedule has its own database selection.
Use Add database instance to register a database, or Add Server in Database Servers to register a remote Linux Docker host.

For MFA-enabled accounts, keep the Authenticator setup key safe. Keep AUTH_TOTP_ENCRYPTION_KEY stable; changing it can prevent verification of stored authenticator seeds.

Before production use: configure unique private API and encryption keys in .env, restrict access to the control plane, and protect the local backup directory. Never paste connection strings or credentials into chat, screenshots, or logs.

2. Navigation and sections

The navigation links move between sections of the DBOps workspace. The active database selector appears in Console, Overview, and Backups; changing it in any of those sections updates the active target across the dashboard. Restore has its own source and destination selectors.

Navigation	What this section does	Steps to use it
Console	Central operations hub. After sign-in, a short welcome screen automatically plays the database data-corridor animation, then opens the Console. The Console itself keeps its standard command-center summary, with an active-target selector and target carousel, active-database actions, and remote-server cards grouped below.	Sign in — after a few seconds the welcome screen continues to Console automatically. Choose Continue to Console or press `Esc` to skip it. Use the active-target selector in the Console header, or choose a database from the target carousel by clicking a card, dragging, using the arrow buttons, or pressing the left/right arrow keys while the carousel is focused. Use the active-target actions or register/manage remote hosts under Database Servers.
Overview	Health and performance for the active target: system status bar (connection, latency, engine version, uptime), key metric cards (recent migrations, storage consumed, slow queries and deadlocks), Migration History, and Active Queries with a Kill action.	Use the Active target selector at the top of Overview to switch databases without returning to Console. Read the metric cards; they refresh about every eight seconds. Press Refresh for an immediate update or pause live refresh in the header. Use Refresh history for migrations, and Kill only to cancel a query you intend to interrupt.
Backups	PostgreSQL snapshot management for the active target. Lists every snapshot with ID, filename, format, size, status, age, and created time, plus per-row Verify, Download, and Restore actions and a snapshot-size trend.	Use the Active target selector in Backups and choose a PostgreSQL target. Click Take Snapshot, choose format, compression, encryption, and optional remote copies, then Start Snapshot. Use Verify to check integrity or Download to retrieve the archive. Open Backup Schedule to automate snapshots.
Restore	Restore and disaster recovery center. Lists restore jobs (ID, backup, mode, destination, status, duration, started) and hosts the New Restore workflow and Refresh control.	Click New Restore (or Restore on a snapshot row). Choose a completed snapshot and a source copy (local, mounted, or checksum-verified remote server). Select a destination: a new database (recommended) or an existing registered PostgreSQL database. Type the confirmation phrase (`RESTORE` or `RESTORE EXISTING`) and click Restore Now. Watch status and logs in this section, then use Refresh to update the list.
Restored DBs	Lists databases produced by clone restores (database name, destination server, monitoring state, and a connection-URL action). This is where you find a freshly restored database and share its URL.	Complete a clone restore (mode = new database) from the Restore section. Open Restored DBs — the new database appears automatically. If it is not yet monitored, click Add to Targets; use Remove from Targets to stop monitoring only. Administrators click the URL action to copy the credential-bearing connection string; copy is not available to non-admin users.
Data Browser	Read-only browser for tables, collections, and a bounded page of rows from a selected target.	Select a database and table or collection. Click Load rows; requests are read-only and limited to 200 rows.
Activity	Shared operations timeline with per-operator colored branches, at-a-glance counters (today / recent events), and a Clear Log control.	Open Activity to review recent snapshots, pings, verifications, restores, and target switches. Follow each operator branch from newest to oldest. Use Clear Log only when you intend to empty the feed.

The header also provides the command palette (Ctrl+K / ⌘+K), the Telegram notification settings, the light/dark theme control, and sign-in/user controls. Exact cards can vary with the database engine and account permissions.

3. Registering and removing database targets

Add a database

Click Add database instance.
Enter a display label and connection URL. Supported schemes include postgresql://, mongodb://, mongodb+srv://, mysql://, and redis://; the engine is detected from the URL and can be reviewed in the form.
Click Test Connection to check connectivity, then Add Database.
Select its target pill to view its dashboard.

The connection test and monitoring queries are intended to read telemetry. The account still needs enough permissions to read the metrics being displayed. Store connection credentials securely and use a monitoring account with limited privileges.

Remove a target from monitoring

Select the target and click Unregister. This removes its entry from the app registry. It does not issue a database drop, modify records, or delete the database.

4. Dashboard and health

The Overview workspace summarizes connection health and available database metrics. Its monitoring cards adapt to the active database engine and the telemetry available to the configured account. Depending on the engine and permissions, it can show storage, query activity, slow operations, table sizes, and lock contention. Use the target selector in Overview to switch databases directly. Database Servers cards show host health such as Docker version, memory, disk use, load average, and DBOps container counts.

Live refresh: dashboard data refreshes automatically about every eight seconds. Use the pause control in the header to stop or resume it; use Refresh to fetch metrics immediately.
Server health: refreshes periodically while the page is visible; the server card also offers a manual health refresh.
Alerts: the header opens Telegram notification settings. Configure the bot, chat, delivery options, and event subscriptions, then save; use Send Test to check delivery.
Kill: where shown for a long-running query, this cancels that operation. It is an active database action; use it only when you intend to interrupt the query.

5. Migration history

The Recent Migrations card and Migration History table provide read-only discovery of recognized PostgreSQL migration ledgers for the selected target. Use Refresh history to check again. DBOps does not apply migrations or change schema/data through this feature.

If enabled in Telegram event subscriptions, New migration detected alerts when a new record appears in a recognized ledger. DBOps checks periodically; the initial scan establishes a baseline and does not alert on records that were already present. A ledger the app does not recognize cannot be reported by this feature.

6. Remote servers

Register a host

On the control-plane machine, connect to the host with terminal SSH and verify its host key. The app requires the matching entry in its configured known_hosts file.
Set SSH_KNOWN_HOSTS_PATH so Docker mounts the trusted file into the app. Unknown or changed host keys are rejected before password authentication.
Set SERVER_CREDENTIAL_ENCRYPTION_KEY to a unique random secret of at least 32 characters. Keep it stable; the app needs it to decrypt registered SSH passwords.
In Database Servers → Add Server, enter the label, IP, SSH port, account, password, and absolute Linux database and snapshot paths.
The path parents must already exist and the SSH account must have the required permissions. The paths may be identical or overlap. Registration checks paths and Docker availability over SSH; it does not create remote files.

Health, provisioning, and removal

Health checks use read-only SSH commands. Create Database Container provisions an isolated PostgreSQL, MongoDB, MySQL/MariaDB, or Redis container with a dedicated data path and protected password file. Choose an unused host port. Provisioning does not repurpose existing containers or data directories. The new connection is registered as a database target. Remove Server removes only the server registration from this app. Containers, files, remote snapshots, and separately registered database targets remain on the host or in the app.

The app rejects path traversal and symlinked path components. Use paths dedicated to DBOps and grant the SSH account only the needed filesystem and Docker access.

7. Taking a manual snapshot

Dashboard monitoring supports multiple database engines, but snapshot and restore operations are currently for PostgreSQL targets.

First select a PostgreSQL target to back up.
Click Take Snapshot from the hero or Backups section. The dialog shows the currently selected target.
Choose an archive format, compression, and optional encryption; add a description if useful.
Optionally check one or more registered remote servers to copy the completed archive to their configured snapshot directories.
Click Start Snapshot. Review the Backups table for status, ID, size, and checksum-related actions.

Custom Archive (.dump): recommended for PostgreSQL; restored with pg_restore.
Plain SQL (.sql / .sql.gz): script format, restored with psql.
Compression: reduces storage use. Custom archives use pg_dump compression; plain scripts use gzip.
Encryption: optional archive encryption. Set a unique BACKUP_ENCRYPTION_KEY before relying on this option and keep a protected copy. Losing or changing the key prevents decryption. The checkbox is labeled “AES-256” in the current UI; confirm the encryption algorithm meets your organization's requirements before depending on a particular strength.
Remote copies: are transferred after the local archive completes. The app verifies SHA-256 before recording a copy as available. A copy failure does not remove the local snapshot.

Manual snapshots are always stored in the configured local backup directory (default ./backups); this dialog offers optional remote-server copies. Mounted repositories can be selected as destinations in the automated schedule.

8. Backup schedule

Click Backup Schedule.
Choose Every day, Every week, or Every month.
Choose the time in UTC. The preview also shows the equivalent Sri Lanka time (UTC+5:30). Weekly schedules include the Sri Lankan weekday if the date changes across time zones.
For a weekly schedule, choose a weekday. For monthly, choose day 1–28 so it exists in every month.
Set status to Active and click Save Schedule. Choose Disabled to pause scheduled backups.

Select the PostgreSQL database to back up and optionally select mounted repositories and/or registered remote servers as additional destinations. Every scheduled snapshot is saved locally, and selected destinations receive copies that are checksum-verified. The schedule is independent of the active dashboard target. The default schedule is daily at 02:00 UTC (07:30 Sri Lanka time); the dialog displays the next run in UTC and Sri Lanka time. If an existing custom schedule is loaded, you can keep it using the current schedule option.

Local snapshots older than the configured retention period are removed by the app’s retention cleanup. The default is 14 days. This applies to local archive files; it does not remove remote server copies.

9. Verify and manage snapshots

In the Backups table, use Verify to check archive integrity without restoring it. A valid archive is not a complete disaster-recovery test; periodically restore a snapshot to a disposable target and confirm the resulting database works.

Use Download to retrieve an archive from local app storage. Keep at least one protected copy outside the machine hosting the control plane if that machine is part of your failure scenario. Remote copies use the registered server’s snapshot path and are not removed when that server is unregistered.

10. Restoring a snapshot and restored databases

New database: the snapshot is loaded into a fresh PostgreSQL database, leaving existing databases unchanged. Existing database: the public schema in the selected database is dropped and recreated before restoring the snapshot. This removes existing objects in that schema, including objects absent from the snapshot. The reset and restore run in one transaction, so a restore error rolls them back. This operation may hold locks; use it only when replacing that schema is intended.

Choose a completed snapshot with Restore in the Backups table, or click New Restore to choose a snapshot.
Select the local or mounted copy, or a registered remote server with a checksum-verified copy. Remote copies support new-database restores only.
Choose a registered PostgreSQL destination. Create a separate new database (recommended) and enter an unused name, or explicitly choose to write into an existing registered database.
Type the confirmation phrase displayed in the dialog: RESTORE for a new database or RESTORE EXISTING for an existing database.
Review the restore plan and click Restore Now. Follow status and logs in Restore Center. The source archive is checksum-verified and staged locally before restore.

Snapshot exports omit owner and privilege settings, so configure roles, grants, and ownership separately as needed.

Restored Databases

The Restored DBs section lists clone restores. If a restored database is not yet in Targets, select Add to Targets to monitor it. Administrators can copy a full connection URL from this section; treat the URL as a credential. It uses the app’s Docker network name; users connecting from outside Docker may need a reachable host name or IP and the published PostgreSQL port. Remove from Targets removes its monitoring entry only; it does not delete the database or its data.

11. Users and multi-factor authentication

The Users control is available to administrators. Use it to create or remove sign-in accounts. New usernames must be 2–32 characters using letters, numbers, underscores, periods, or hyphens; temporary passwords must be at least 12 characters.

MFA is optional per account. When creating a user, select Enable Microsoft Authenticator (MFA) only if that account should require MFA. If selected, securely provide the displayed QR code or manual setup key to the user for enrollment. If it is not selected, that user signs in with username and password and is not prompted for an Authenticator code.

Share MFA setup details and temporary passwords securely. Never include them in screenshots, chat, or support logs.

12. Activity and shortcuts

The Activity section shows recent operations such as snapshots, pings, verifications, and target switches, grouped into operator branches. Use Clear Log only when you intend to clear the activity feed. The header’s command palette searches actions and registered databases; open it with Ctrl+K (or ⌘+K on macOS), then select a result. Use the theme control to switch between light and dark appearance.

13. Safety boundaries and credentials

Registering a database adds a connection record to the app; it does not copy the database.
The Migration History panel and migration alert monitor check recognized PostgreSQL migration ledger tables with read-only SELECT queries. They never run migrations or change schema/data. Migration alerts identify new records in recognized ledgers; an unrecognized or external ledger cannot be monitored by this feature.
Monitoring and connectivity checks query metrics; the explicit Kill action cancels a running query.
Taking a snapshot reads from the source database. A new-database restore creates a separate database. An existing-database restore writes the selected snapshot's objects and data into the chosen database; use the explicit confirmation and understand it can affect application workload.
Remote server registration does not create remote files. Provisioning creates a new DBOps container and new files below the configured database path. Snapshot replication creates new files below the configured snapshot path.
Removing a server or unregistering a database removes its app registration only. Neither operation deletes remote data or stops a container.
Keep .env, database URLs, SSH passwords, SSH host keys, and encryption keys private. Back up the encryption keys separately from encrypted archives.

14. Troubleshooting

Connection test or monitoring fails: check the connection URL, network/firewall, database availability, and account permissions.
An account receives an unexpected MFA prompt: ask an administrator to confirm whether MFA was enabled for that account. MFA is not required for accounts created without the option selected.
SSH says host not found in known_hosts: verify the host key with terminal SSH on the control-plane machine, then ensure the exact trusted entry is present in the file mounted at SSH_KNOWN_HOSTS_PATH. Do not bypass host-key checks.
Credential encryption key error: set a unique SERVER_CREDENTIAL_ENCRYPTION_KEY of at least 32 characters, then restart the app.
Remote path error: use an absolute Linux path, confirm its parents already exist, and confirm there are no symlinked path components.
Remote snapshot missing: verify that the copy completed and is listed as checksum-verified on the selected server. A local snapshot alone does not imply that a remote copy exists.
Restore fails because the name exists: choose a different unused name for a new-database restore. For an existing-database restore, check the selected destination and the confirmation phrase before trying again.

Avoid including passwords, keys, or unredacted connection URLs in support messages.