> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbhost.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Start, stop or restart a database

> Start, stop or restart a DBHost PostgreSQL database through the API. Stop blocks new connections and ends sessions; data is kept.

Starts, stops or restarts one database. The request waits until the action
has finished and returns the new status. Selected-database keys can use this
route for databases they are assigned to; full-account keys for any database
you own. API access requires a Pro or Business plan.

| Action | Effect | Resulting `status` |
| - | - | - |
| `stop` | Blocks new connections and ends active sessions. Data stays on disk. | `stopped` |
| `start` | Allows connections again and waits until pooled clients can connect | `active` |
| `restart` | Ends active sessions, then allows connections again and waits until pooled clients can connect | `active` |

Applications lose their open connections on `stop` and `restart`. Stopping a
database does not delete it or its backups.

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `action` | string | Yes | `start`, `stop` or `restart` |

```http theme={null}
POST /api/v1/databases/{id}/lifecycle
Authorization: Bearer <api-key>
Content-Type: application/json

{"action":"stop"}
```

## Response

```json 200 OK theme={null}
{
  "message": "Database stopped. New connections are blocked until it is started again.",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "stopped"
  }
}
```

The action is recorded in the database's activity log.

## Errors

| Status | Code | Description |
| - | - | - |
| 400 | `VALIDATION_ERROR` | `action` is missing or not `start`, `stop` or `restart` |
| 400 | `INVALID_JSON` | Request body is not valid JSON |
| 401 | `UNAUTHORIZED` | Missing or invalid API key |
| 403 | `PLAN_API_ACCESS_REQUIRED` | The account is not on Pro or Business |
| 404 | `DATABASE_NOT_FOUND` | Database does not exist or is not visible to this key |
| 409 | State code, for example `DATABASE_STOPPED` | The database's current state does not allow the action |
| 413 | `PAYLOAD_TOO_LARGE` | Request body is larger than 64 KB |
| 429 | `RATE_LIMITED` | Too many requests; retry after `Retry-After` seconds |
| 502 | `AGENT_ERROR` | DBHost could not complete the action; check the status and retry |
| 503 | `MAINTENANCE` | Scheduled maintenance; retry after `Retry-After` seconds |

During maintenance the body is `{"error":"MAINTENANCE","message":"..."}`
instead of the standard error envelope.

The dashboard has the same controls in the database's operations menu; see
[Databases](/dashboard/databases). The CLI equivalent is
`dbhost databases start|stop|restart <id>`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.