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

# Database

> The managed Postgres database, one per environment (production by default); credentials are issued once and rotatable on demand.

The managed Postgres database, one per environment (production by default); credentials are issued once and rotatable on demand.

## database.get

Get the environment's database status and connection details (never the password).

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/database
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Query parameters

| Name          | Type   | Required | Description                        |
| ------------- | ------ | -------- | ---------------------------------- |
| `environment` | string | No       | Pattern: `^[a-z][a-z0-9-]{0,38}$`. |

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/database?environment=example" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                                   |
| ------ | --------------------------------------------- |
| `200`  | The database.                                 |
| `404`  | No database provisioned for this environment. |

### Response body (200)

| Field    | Type    | Description                                                          |
| -------- | ------- | -------------------------------------------------------------------- |
| `status` | string  | One of: `provisioning`, `ready`, `failed`.                           |
| `region` | string  | Database region id (see regions.list). Immutable after provisioning. |
| `host`   | string  | Managed database endpoint ("db.korve.app").                          |
| `port`   | integer | —                                                                    |
| `dbName` | string  | —                                                                    |
| `user`   | string  | —                                                                    |

## database.provision

Provision the environment's database and issue its credentials (production by default).

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/database
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `write`

### Query parameters

| Name          | Type   | Required | Description                        |
| ------------- | ------ | -------- | ---------------------------------- |
| `environment` | string | No       | Pattern: `^[a-z][a-z0-9-]{0,38}$`. |

### Request body (optional)

| Field    | Type   | Required | Description                                                                                            |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `region` | string | No       | Database region id (see regions.list); defaults to the platform default. Immutable after provisioning. |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/database?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "region": "example"
}'
```

### Responses

| Status | Description                                                                                               |
| ------ | --------------------------------------------------------------------------------------------------------- |
| `201`  | Database provisioned. The connection string is shown once; store it securely. Rotate to obtain a new one. |
| `402`  | Organization billing is not active.                                                                       |
| `404`  | No such project or environment in this organization.                                                      |
| `409`  | This environment already has a database.                                                                  |
| `422`  | Unknown or unavailable database region.                                                                   |

### Response body (201)

| Field              | Type   | Description                                                                                                     |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------- |
| `status`           | string | One of: `provisioning`, `ready`, `failed`.                                                                      |
| `connectionString` | string | Full postgres\:// connection string including the password. Shown exactly once — it is never retrievable later. |

## database.rotatePassword

Rotate the database password. The old password stops working immediately.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/database/rotate
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Risk:** `write` · sensitive (elevated blast radius)

### Query parameters

| Name          | Type   | Required | Description                        |
| ------------- | ------ | -------- | ---------------------------------- |
| `environment` | string | No       | Pattern: `^[a-z][a-z0-9-]{0,38}$`. |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/database/rotate?environment=example" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| `200`  | New credentials issued. The connection string is shown once; store it securely. Rotate to obtain a new one. |
| `404`  | No database provisioned for this environment.                                                               |

### Response body (200)

| Field              | Type   | Description                                                                                                     |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------- |
| `connectionString` | string | Full postgres\:// connection string including the password. Shown exactly once — it is never retrievable later. |

## database.delete

Delete the environment's database and all of its data. This cannot be undone.

```text theme={null}
DELETE /v1/orgs/{orgId}/projects/{projectId}/database
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `owner`
* **Risk:** `destructive` · sensitive (elevated blast radius)

### Query parameters

| Name          | Type   | Required | Description                        |
| ------------- | ------ | -------- | ---------------------------------- |
| `environment` | string | No       | Pattern: `^[a-z][a-z0-9-]{0,38}$`. |

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/database?environment=example" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                                   |
| ------ | --------------------------------------------- |
| `200`  | Database deleted.                             |
| `404`  | No database provisioned for this environment. |