Managing databases

​

Creating a database

1. Click + New Database from the dashboard
2. Enter the database name you want to see in the dashboard
3. Click Create

DBHost generates the internal PostgreSQL identifier from the display name and your account, then redirects to the detail page with success/readiness state, the connection string, and psql, Prisma, and Drizzle examples.

​

Dashboard list

The main dashboard shows every database you can access.

• Owned databases appear normally
• Shared databases stay in the same list and include your effective access role
• Search and status filters help when the list grows
• Status filters include active, stopped, provisioning, and deleted/recovery views where the current release gate allows them
• Environment filters use one optional value: production, staging, development, or other
• Size values are hydrated from live agent metrics when the VPS is reachable

​

Database detail page

Click any database card to see its details:

• Connection details — Host, port, database name, username
• Connection string — Copy-paste ready (password masked, click to reveal)
• Metrics — Current size, live clients, waiting clients, and last connection seen
• Actions — A dedicated SQL Explorer card plus a separate operations card for backups, lifecycle, password resets, and owner-only guarded deletion
• Team access — Owner plus any shared members and their database role
• IP whitelist — Per-database CIDR rules applied at the PgBouncer layer
• Connection activity — Recent observed client connections
• Recent activity — Audit-log history for the database
• Backups — View backup history, trigger new backups, download backup files, delete backup files

DBHost stores tenant database passwords encrypted at rest in the control plane. When you reveal or reset a password from the detail page, DBHost decrypts the current secret or replaces it for the authorized session.

​

Team access

Every database detail page includes a Team Access section. Owners and database admins can invite by email and assign one of these roles: An existing DBHost user receives membership directly. An unknown normalized email creates a local pending-invitation row and a Clerk invitation with a seven-day expiry. Resending revokes the prior Clerk invitation before creating the replacement. Database and role data stays in the local row, not Clerk public metadata. Acceptance during first sign-in is idempotent. The owner is always shown separately and cannot be removed or downgraded through the member flow. Pending invitations and idempotent first-sign-in acceptance are active.

​

Deleted database recovery

Owners can recover a deleted database during its seven-day recovery window when their current plan has available quota. Tombstones reserve the database name without consuming active quota. The dashboard database list has stable Active and Recently deleted views. A deleted card shows the deletion time, local permanent-deletion deadline, remaining time and exact verified deletion-backup metadata. The database is disconnected and unavailable while it is in this view. The owner can download the deletion backup regardless of quota, or start recovery when an active database slot is available. Deletion requires the exact internal name, an operation-bound canonical database identity, managed-registry/OID verification and a fresh verified deletion backup. After those checks pass, DBHost removes routing and keeps the database isolated with its backup artifact for recovery. A database that fails any identity, backup, capability or protected-target check is not deleted. Recovery restores the previously active team memberships, IP allowlist and still-existing owner-controlled selected-database API-key bindings from the immutable deletion snapshot. Missing users or API keys are skipped and shown as a warning without failing database recovery. Pending and expired invitations are not restored. After seven days, recovery and download are disabled and the card reads Permanent deletion pending. The automatic worker then permanently removes the exact PostgreSQL tombstone and every S3 version of the operation-bound deletion backup. A transient retry can briefly delay this final step. The row disappears from the dashboard only after both removals are confirmed.

​

IP whitelist

The IP Whitelist section controls which client networks can connect through PgBouncer.

• Add CIDR blocks such as 203.0.113.0/24
• Optional labels help explain why a rule exists
• If the allowlist is empty, the database accepts connections from any IP
• As soon as you add one or more CIDR blocks, only matching networks can connect

These rules affect direct database connections through port 6432. They do not change dashboard sign-in behavior.

​

Start, stop, and restart

The operations menu on the detail page includes lifecycle controls when your role allows it.

• Start re-enables a stopped database and waits until pooled client connections are usable again
• Stop prevents new pooled connections and moves the database into the stopped state
• Restart refreshes the pooled runtime without deleting the database

Stopping a database is operational, not destructive. Data remains on disk. Database deletion is a separate guarded soft-delete workflow.

​

Connection activity

The detail page includes a Connection Activity section with the most recent observed PgBouncer client connections for that database. Each row includes:

• database username
• client IP address
• application name when provided by the client
• connection timestamp
• source label

The metrics card above it also surfaces live client counts and waiting clients from PgBouncer when the agent is reachable.

​

Data Explorer

Every database detail page includes a dedicated SQL Explorer action card, so the query workspace is always a first-class path instead of being hidden inside the operations menu. The explorer has two tabs:

• Tables — List public tables and preview rows with pagination
• SQL Query — Run one guarded read-only SQL statement at a time against the selected database

The explorer header makes the current database explicit and lets owners switch to another owned database without leaving the page. In the SQL tab, the editor stays central while a companion utility rail keeps selected table context, saved queries, recent history, and starter snippets nearby through Suggested, Saved, and Recent panes. Typing / opens a command drawer inside the editor for quick inserts, and using / after FROM or JOIN turns that drawer into a scoped table picker so you do not have to leave the explorer to remember names. A small editor settings menu lets each user turn slash commands, table suggestions, and the helper rail on or off on their own device. Saved queries are stored per user and per database. The Saved pane lets you create named presets, mark favorites so they stay first, and reopen or edit the SQL already in the editor. The Recent pane shows the latest query runs for the current database and lets you choose how many recent runs DBHost should remember for your account. The explorer also supports a safe inspect subset inspired by psql:

• \dt, \dv, \di, and \d <relation>
• Matching /dt, /dv, /di, and /d <relation> aliases
• Optional convenience forms such as \d FROM "analytics_downloads" and /dt FROM "analytics_downloads"

The editor shortcut hints reflect the current behavior:

• / opens commands
• Esc dismisses the open helper
• Ctrl+Enter or Cmd+Enter runs the current query
• Ctrl+C clears the editor when no text is selected

Saved presets and recent history use the latest explorer persistence migration when it is available. If that migration is still pending, DBHost falls back to browser-local storage for the current user and database until server-backed persistence is ready. Explorer queries are limited to the selected database and the public schema. The in-app guardrails allow:

• SELECT
• EXPLAIN SELECT

The explorer blocks multi-statement input, INSERT, UPDATE, DELETE, CREATE, DROP, TRUNCATE, ALTER, transaction/session control, and system-schema access.

​

Resetting a password

If you need a new password:

1. Go to the database detail page
2. Click Reset Password
3. A new password is generated and the old one stops working immediately

The replacement secret is stored encrypted at rest, and the previous password is invalidated as part of the rotation.

​

Deleting a database

Owners and system administrators can select Delete database from the database’s Manage database menu. Database admins, developers and viewers cannot delete a database. The confirmation dialog requires the exact internal database name. DBHost then creates and verifies a deletion backup, verifies the canonical database ID/name and managed-registry/OID binding, removes routing, and retains an isolated tombstone and backup artifact for a seven-day recovery window. Final physical purge is a separate, expired-tombstone operation. It is not a customer menu action and is not authorized by the delete feature flag alone. Automatic purge is independently gated and operates only on a bounded, deterministically ordered list of expired tombstones.

​

Database statuses