How-to guide

Register a database

Registering a database tells Workbench the shape of the machine your PostgreSQL runs on — its Target environment. Findings account for that shape, so a recommendation for a 4 vCPU managed instance differs from one for a 64-core bare-metal box. This is operator-declared metadata; Workbench never connects to the database to discover it.

What the Target environment is

The Target environment is the operator-declared shape of the host: its CPU, memory, storage class, platform (managed service or self-managed), and workload profile. It is separate from collection — the Signals collector reads the database's statistics; the Target environment is the context the analyzer uses alongside them so its findings fit your actual hardware.

Edit through the UI (recommended)

Open the database in Workbench and follow Edit target (/databases/<id>/target/edit). There are two ways to fill it in:

Cloud preset (recommended for managed Postgres) — pick your instance SKU and Workbench fills the CPU / RAM / storage shape for you.
Manual entry — for self-managed or a SKU not in the preset list, enter the values directly.

Saving upserts the database's target row; the analyzer reads it on its next run.

Edit through the API (automation)

For scripted onboarding, use the target-only PATCH endpoint:

WORKBENCH=http://127.0.0.1:8080
DB_ID=<database-id>

curl -fsS -X PATCH "$WORKBENCH/api/databases/$DB_ID/target" \
  -b /tmp/wb.cookies \
  -H 'Content-Type: application/json' \
  -H "X-Arq-CSRF: $(grep arq_workbench_csrf /tmp/wb.cookies | awk '{print $7}')" \
  -d '{
        "cpu_cores": 8,
        "ram_gb": 32,
        "storage_type": "cloud_managed",
        "iops": 12000,
        "throughput_mbps": 750,
        "platform": "rds",
        "workload": "oltp",
        "cloud_preset_sku": "db.m6i.2xlarge"
      }'

The closed-enum fields are the wire contract: storage_type is one of nvme / ssd / hdd / cloud_managed; platform is one of self_hosted / rds / aurora / cloud_sql / azure_flex / alloydb; workload is oltp / olap / mixed. An out-of-enum value is rejected with DATABASE_VALIDATION_ERROR.

A populated body upserts — fields you omit keep their current value. An empty body clears the target row, useful when you want findings without a hardware assumption.

With targets registered and Signals collecting, the analyzer produces findings you review in Workbench. For what a finding looks like and how to read one, see the evaluation guide.