Manage Databases

Start, stop, restart, and resize your databases.

Start Database

Resume a stopped database.

POST /v1/databases/{id}/start

curl -X POST https://api.cloudheed.com/v1/databases/db-abc123/start \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "id": "db-abc123",
  "status": "starting",
  "message": "Database is starting up"
}

Stop Database

Stop a running database to save costs.

POST /v1/databases/{id}/stop

curl -X POST https://api.cloudheed.com/v1/databases/db-abc123/stop \
  -H "Authorization: Bearer YOUR_TOKEN"

Stopped databases don't incur compute charges, but storage charges still apply.

Restart Database

Restart a database to apply configuration changes.

POST /v1/databases/{id}/restart

curl -X POST https://api.cloudheed.com/v1/databases/db-abc123/restart \
  -H "Authorization: Bearer YOUR_TOKEN"

Resize Database

Upgrade or downgrade your database tier.

POST /v1/databases/{id}/resize

curl -X POST https://api.cloudheed.com/v1/databases/db-abc123/resize \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "small"
  }'

Parameters

Field	Type	Required	Description
`tier`	string	Yes	New tier (`micro`, `small`, `medium`, etc.)

⚠️

Resizing requires a brief restart (typically under 30 seconds). Plan accordingly.

Reset Password

Generate a new database password.

POST /v1/databases/{id}/reset-password

curl -X POST https://api.cloudheed.com/v1/databases/db-abc123/reset-password \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "password": "new-generated-password",
  "connection_string": "postgresql://cloudheed:[email protected]:5432/postgres?sslmode=require"
}

🚫

This invalidates the previous password immediately. Update your application configuration.

Operation Status

All operations return immediately and process asynchronously. Poll the database endpoint to check status:

curl https://api.cloudheed.com/v1/databases/db-abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Status Values

Status	Description
`starting`	Database is starting up
`stopping`	Database is shutting down
`resizing`	Resources are being adjusted
`running`	Operation complete, database is ready
`stopped`	Database is stopped
`failed`	Operation failed

Best Practices

Schedule maintenance - Resize during low-traffic periods
Monitor after changes - Check metrics after resizing
Use connection pooling - Reduce restart impact with PgBouncer
Automate scaling - Use metrics to trigger resize operations

Create Database Configuration