Databases API
Provision PostgreSQL databases, manage database connections, and handle backups.
POST /api/projects/:id/databases/provision
Provisions a new PostgreSQL database for a project environment. Returns the connection credentials once — the password will not be shown again. Requires DEVOPS role. Audit-logged.
Auth: Bearer token (DEVOPS)
Request Body:
{
"environment": "staging"
}
Response 201:
{
"dbName": "my-app-staging",
"username": "my_app_staging_user",
"password": "generated-password",
"host": "postgres-service.databases.svc.cluster.local",
"port": 5432,
"connectionString": "postgresql://my_app_staging_user:[email protected]:5432/my-app-staging",
"message": "Database provisioned. Save these credentials — the password will not be shown again."
}
Database Connections
GET /api/db-connections
Lists database connections. Can be filtered by projectId query parameter.
Auth: Bearer token (any authenticated user)
Query Parameters:
| Param | Type | Description |
|---|---|---|
| projectId | uuid | Filter by project |
Response 200:
[
{
"id": "uuid",
"projectId": "uuid",
"dbType": "postgres",
"poolSize": 10,
"status": "connected",
"activeCount": 2,
"idleCount": 8,
"lastHeartbeat": "2026-07-01T12:00:00.000Z"
}
]
DbType values: postgres, mongo, redis
Status values: connected, degraded, disconnected
POST /api/db-connections
Creates a new database connection record. Requires DEVOPS role.
Auth: Bearer token (DEVOPS)
Request Body:
{
"projectId": "uuid",
"dbType": "postgres",
"poolSize": 20
}
Response 201:
{
"id": "uuid",
"projectId": "uuid",
"dbType": "postgres",
"poolSize": 20,
"status": "connected",
"lastHeartbeat": "2026-07-01T12:00:00.000Z"
}
POST /api/db-connections/:id/test
Tests a database connection by updating its status and simulating latency.
Auth: Bearer token (any authenticated user)
Response 200:
{
"status": "connected",
"latencyMs": 12
}
DELETE /api/db-connections/:id
Deletes a database connection record. Requires DEVOPS role.
Auth: Bearer token (DEVOPS)
Response 200:
{ "success": true }
Database Backups
POST /api/projects/:projectId/databases/backup
Triggers an asynchronous database backup using pg_dump. The backup is uploaded to the active storage provider. An SMTP notification is sent to DEVOPS users on completion. Requires DEVOPS role. Audit-logged.
Auth: Bearer token (DEVOPS)
Request Body:
{
"dbName": "my-app-production",
"environment": "production"
}
Response 202:
{
"backupId": "uuid",
"status": "in_progress",
"message": "Backup started. You will be notified when complete."
}
GET /api/projects/:projectId/databases/backups
Lists backups for a project. Can be filtered by dbName query parameter.
Auth: Bearer token (any authenticated user)
Query Parameters:
| Param | Type | Description |
|---|---|---|
| dbName | string | Filter by database name |
Backup Statuses: pending, in_progress, completed, failed, restoring
Response 200:
[
{
"id": "uuid",
"projectId": "uuid",
"dbName": "my-app-production",
"environment": "production",
"providerType": "minio",
"fileId": "backups/my-app/my-app-production/dump_...",
"fileSizeBytes": 1048576,
"checksum": "sha256-checksum",
"status": "completed",
"createdAt": "2026-07-01T12:00:00.000Z"
}
]
POST /api/projects/:projectId/databases/backups/:backupId/restore
Restores a database from a completed backup. Downloads the backup file from the storage provider and runs pg_restore. Requires DEVOPS role. Audit-logged.
Auth: Bearer token (DEVOPS)
Response 202:
{
"message": "Restore started",
"backupId": "uuid"
}
Error 400:
{ "error": "Backup is not in completed state" }
Error Codes
| Status | Error | Description |
|---|---|---|
| 400 | environment is required |
Missing environment on provision |
| 400 | dbName is required |
Missing dbName on backup |
| 400 | Backup is not in completed state |
Cannot restore an incomplete backup |
| 404 | Project not found |
Invalid projectId |
| 404 | DB Connection not found |
Invalid connection ID |