Database

Provision and manage PostgreSQL databases for your applications.

Provision Database

POST /v1/projects/:id/database

curl -X POST https://api.sota.io/v1/projects/550e8400-.../database \
  -H "Authorization: Bearer <token>"

Response (201 Created):

{
  "data": {
    "id": "db-550e8400",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "provisioning",
    "host": "sota-db-my-app",
    "port": 5432,
    "db_name": "my-app",
    "db_user": "app_my-app",
    "created_at": "2026-02-25T10:00:00Z",
    "updated_at": "2026-02-25T10:00:00Z"
  }
}

What Happens

1. A PostgreSQL 17 container is created (sota-db-{slug})
2. A PgBouncer sidecar is created for connection pooling (sota-pgbouncer-{slug})
3. A cryptographically random password is generated (32 hex characters)
4. The DATABASE_URL environment variable is automatically injected into your app container

You do not need to manually configure the database connection. The DATABASE_URL is available in your app as:

postgresql://app_{slug}:{password}@sota-pgbouncer-{slug}:5432/{slug}?sslmode=disable

Note: The database password is encrypted and never exposed via the API.

Auto-provisioning: Databases are also auto-provisioned on first deploy. You do not need to call this endpoint manually unless you want to provision before the first deployment.

Get Database Status

GET /v1/projects/:id/database

Returns the database connection details (without password).

Deprovision Database

DELETE /v1/projects/:id/database

Returns 204 No Content. This permanently removes the database and all data. This action is irreversible.

Connection Pooling

Every database includes a PgBouncer sidecar with transaction pooling:

Backups

Databases are automatically backed up daily using pg_dump with gzip compression.

List Backups

GET /v1/projects/:id/database/backups

Returns an array of backup metadata (name, size, created_at).

Trigger Manual Backup

POST /v1/projects/:id/database/backups

Creates an on-demand backup and returns the backup metadata (201 Created).