Monitoring

AxiomDB provides real-time monitoring of your PostgreSQL databases — CPU, memory, active connections, cache hit ratio, storage, and provisioning job status. Data is streamed from the VPS via square-dbctl.

System health

Check the gateway's own health (unauthenticated):

GET /api/v1/health

Response (200 OK):

{
  "status": "ok",
  "timestamp": "2025-07-02T12:00:00Z"
}

Project metrics

Get storage and connection metrics for a project's databases:

GET /api/v1/projects/:project_id/metrics
Authorization: Bearer <paseto-v4-token>

Response:

{
  "project_id": "...",
  "databases": [
    {
      "database_name": "sq_servers_prod",
      "size_bytes": 52428800,
      "active_connections": 5,
      "max_connections": 100,
      "cache_hit_ratio": 0.972,
      "branch_name": "main",
      "is_default": true
    },
    {
      "database_name": "sq_servers_prod_br_feature-auth",
      "size_bytes": 4194304,
      "active_connections": 1,
      "max_connections": 100,
      "cache_hit_ratio": 0.943,
      "branch_name": "feature-auth",
      "is_default": false
    }
  ],
  "project_total_size_bytes": 56623104,
  "storage_limit_bytes": 10737418240,
  "branch_count": 2
}

Branch-level metrics summary

GET /api/v1/projects/:project_id/branches/:branch_ref/metrics/summary
Authorization: Bearer <paseto-v4-token>

Returns the same data scoped to a single branch:

{
  "project_id": "...",
  "branch_id": "...",
  "branch_name": "feature-auth",
  "database": "sq_servers_prod_br_feature-auth",
  "metrics": {
    "database_size_bytes": 4194304,
    "active_connections": 1,
    "cache_hit_ratio": 0.943
  },
  "usage": {
    "storageUsedBytes": 56623104,
    "storageLimitBytes": 10737418240
  }
}

Provisioning jobs

All async operations (project provisioning, branch creation, deletion, backup restore) create a provisioning_jobs record you can poll.

GET /api/v1/jobs/:job_id
Authorization: Bearer <paseto-v4-token>

Response:

{
  "id": "...",
  "project_id": "...",
  "action": "provision",
  "status": "succeeded",
  "requested_by": "...",
  "request_payload": { "app_key": "servers", "env": "prod" },
  "output": { "database": "sq_servers_prod", "owner_role": "servers_prod_owner", "..." },
  "error_text": null,
  "started_at": "2025-07-02T00:00:05Z",
  "finished_at": "2025-07-02T00:00:23Z",
  "created_at": "2025-07-02T00:00:00Z"
}

Job statuses

Status	Description
`pending`	Queued in Redis, not yet picked up
`running`	Worker is executing `square-dbctl`
`succeeded`	Completed successfully
`failed`	`square-dbctl` returned non-zero; see `error_text`

Job types

Action	Trigger
`provision`	`POST /api/v1/projects`
`deprovision`	`DELETE /api/v1/projects/:id`
`branch_create`	`POST /api/v1/projects/:id/branches`
`branch_delete`	`DELETE /api/v1/projects/:id/branches/:id`
`smoke`	Manual smoke-test call
`restore_plan`	`POST /api/v1/projects/:id/backups/restore-plan`
`restore`	`POST /api/v1/projects/:id/backups/restore`

Monitoring dashboard (ops console)

The dbs web console Monitoring page provides:

CPU usage graph — 24h history, polled every 30 seconds
Memory usage — total, used, available
Active database connections — per-database breakdown
Cache hit ratio — for each project database
Storage usage bar — used vs limit with % indicator
Provisioning job history — sortable list of recent jobs with status badges

Metrics are fetched from the gateway which internally runs square-dbctl stats --app {app_key} --env {env} on the VPS. Results are NOT cached in the control-plane DB — every request to the metrics endpoint triggers a live read from the VPS.

Alerts & thresholds

The following conditions are surfaced in the console as warnings or errors:

Condition	Threshold	Action
Storage near limit	≥ 80% used	Yellow warning banner
Storage at limit	= 100% used	Red error, branch creation blocked
Circuit breaker open	5 consecutive `square-dbctl` failures	`503` responses for monitoring endpoints
Provisioning job failed	`status = "failed"`	Red badge on Jobs page

Circuit breaker

The gateway wraps all square-dbctl calls with a circuit breaker to prevent cascading failures when the VPS is unreachable.

Default threshold:   5 consecutive failures
Default timeout:     60 seconds
States:              Closed → Open → Half-Open → Closed

When the circuit is Open, all monitoring endpoints that require square-dbctl return 503 Service Unavailable immediately rather than blocking on a slow timeout. After 60 seconds, one probe request is allowed through (Half-Open). If it succeeds, the circuit closes. If it fails, the timeout resets.

On this page