> ## Documentation Index > Fetch the complete documentation index at: https://docs.dbhost.app/llms.txt > Use this file to discover all available pages before exploring further. # Managing databases > Create, view, and manage your PostgreSQL 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: | Role | What it can do | | ------------- | ------------------------------------------------------------------------- | | **admin** | Manage collaborators, lifecycle, network policy, backups, and credentials | | **developer** | View credentials and view/download backups; no backup mutations | | **viewer** | View the database detail page and connection activity only | 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 ` * Matching `/dt`, `/dv`, `/di`, and `/d ` 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. Explorer guardrails only apply inside the dashboard explorer. Direct database connections still use your normal database credentials. ## 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. All active connections using the old password will be disconnected. Update your application's connection string before resetting. ## 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. Deletion immediately disconnects the database from normal routing. Confirm the exact internal name and make sure dependent applications are prepared before continuing. Recovery remains available for seven days, subject to account quota. ## Database statuses | Status | Meaning | | ------------ | ---------------------------------------------------- | | **active** | Running and accepting connections | | **creating** | Being provisioned (usually seconds) | | **stopped** | Provisioned but not accepting new pooled connections | | **deleting** | Being removed | | **error** | Something went wrong during provisioning |