Skip to main content

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.

DBHost is useful when the same database actions keep repeating: list databases, create a new one for a project, trigger backups, or reset a password after a release. This guide shows the shortest path to automating those tasks with the published CLI and the REST API. Best fit: Indie developers, small SaaS teams, and agencies that want repeatable database workflows from a terminal, CI job, or deployment script. Not for: Teams that only need one-off dashboard actions and do not need API access or automation yet.

​
What you need

  • A DBHost account
  • API access on a Pro or Business plan
  • One API key with the smallest scope that fits the job
Use a selected-database key by default. Switch to full-account access only when the job must create databases or act across the whole account.

​
1. Create an API key

Create the key in Settings and copy it immediately. DBHost only shows the full secret once. If the automation only needs to inspect or operate on an existing database, select that database and keep the key scoped narrowly.

​
2. Use the CLI locally

Install or run the published CLI: 
npx @dbhost-app/cli@latest --help
Then log in: 
dbhost auth login --api-key dbh_your_api_key_here
The CLI stores the key locally, so you do not need to pass it every time.

​
3. Use environment variables in CI

For scripts and CI jobs, prefer environment variables instead of interactive login: 
export DBHOST_API_KEY=dbh_your_api_key_here
export DBHOST_API_URL=https://dbhost.app/api/v1
With those set, the CLI can run non-interactively from shell scripts, GitHub Actions, or scheduled jobs.

​
4. Automate the common database workflows

List databases: 
dbhost databases list --json
Create a database: 
dbhost databases create analytics-v2 --display-name "Analytics V2" --json
Trigger a backup: 
dbhost backups trigger <database-id> --json
List, download, or delete a backup file: 
dbhost backups list <database-id> --json
dbhost backups download <database-id> 20260326_222551.sql.gz --output ./latest-backup.sql.gz
dbhost backups delete <database-id> 20260320_030000.sql.gz --yes --json
Without --output, dbhost backups download saves the file to your current working directory using the same backup filename. Reset a password: 
dbhost databases reset-password <database-id> --json
The --json flag is the safest default for automation because it gives you machine-readable output that can be parsed by your job runner.

​
5. Call the API directly when HTTP is simpler

If your system already works with cURL or fetch, call the API directly: 
curl -H "Authorization: Bearer $DBHOST_API_KEY" \
  https://dbhost.app/api/v1/databases
For a create flow, send JSON to the same API the CLI uses: 
curl -X POST https://dbhost.app/api/v1/databases \
  -H "Authorization: Bearer $DBHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"analytics-v2","displayName":"Analytics V2"}'
The REST API and CLI are interchangeable for most workflows. Use whichever one your team already ships with.

​
7. Handle retries without changing your workflow

The CLI commands and REST endpoints keep the same authentication model and success payloads. The main Phase 1 security change for automation is that DBHost now returns:
  • 413 PAYLOAD_TOO_LARGE when a JSON body is too large
  • 429 RATE_LIMITED when a route is being hit too aggressively or when there are too many unauthorized attempts
If you call the API directly, respect the Retry-After header on 429 responses before retrying. If you use the CLI, treat 429 as a temporary backoff condition instead of a permanent failure.

​
6. Keep automation safe

  • Default to selected-database keys
  • Use full-account keys only for database creation or account-wide administration
  • Treat database IDs as UUIDs, not row numbers
  • Revoke keys you no longer need
  • Keep secrets in CI secret storage, not in source control
  • Keep create and mutation jobs bounded; avoid tight retry loops without delay
  • Respect Retry-After when the API returns 429
DBHost’s API and CLI are designed for the same workflows as the dashboard. If you want to verify a flow by hand before automating it, the dashboard shows the same databases, backups, and API key scopes.

​
Example CI job

name: Trigger backup

on:
  workflow_dispatch:
  schedule:
    - cron: "0 3 * * *"

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger DBHost backup
        env:
          DBHOST_API_KEY: ${{ secrets.DBHOST_API_KEY }}
        run: dbhost backups trigger "${{ secrets.DBHOST_DATABASE_ID }}" --json
That pattern keeps the job simple: the secret stays in the CI system, the command stays readable, and the output is easy to log or inspect.

​
Next steps

Start for Free

Create an account now, then move to a paid plan when you need API access.

API Reference

Use the REST API directly when HTTP fits your workflow better than the CLI.
  • Read the CLI reference for the full command list.
  • Read the API introduction for the request and response shape.
  • Read API keys if you want a deeper look at scopes and revocation.