# Databases

> Source: https://developers.cloud66.com/v3/endpoints/databases/

## List Databases

URL: https://developers.cloud66.com/v3/endpoints/databases/#list
Endpoint: GET /stacks/:stack_id/server_groups/:server_group_id/databases
OAuth scope: public

Returns a paginated collection of databases associated with the specified server group.

This endpoint triggers an asynchronous info retrieval operation to ensure database information is current before returning the results. Only works with server groups that support database operations.

**Related models:** Database, Server Group, Pagination

<ResponseCodes 
  codes={[200, 400, 401, 403, 404]}
  overrides={{
    200: "Success - Returns paginated list of databases",
    400: "Bad Request - Server group does not support database operations",
    403: "Forbidden - OAuth token lacks required `public` scope",
    404: "Not Found - Stack or server group not found"
  }}
/>

### Parameters

- `stack_id` (string, optional) — Stack ID
- `server_group_id` (string, optional) — Server group ID
- `page` (string, optional) — Page number for pagination (defaults to 1, minimum 1)

### Response

```json
{
  "response": [
    {
      "uid": "db_abc123",
      "name": "app_production",
      "charset": "utf8mb4",
      "collation": "utf8mb4_unicode_ci",
      "size_bytes": 104857600,
      "created_at": "2023-01-15T10:30:00Z",
      "users": ["app_user", "readonly_user"]
    },
    {
      "uid": "db_def456", 
      "name": "analytics_db",
      "charset": "utf8mb4",
      "collation": "utf8mb4_unicode_ci",
      "size_bytes": 52428800,
      "created_at": "2023-01-10T14:20:00Z",
      "users": ["analytics_user"]
    }
  ],
  "count": 2,
  "pagination": {
    "previous": null,
    "next": null,
    "current": 1,
    "per_page": 30,
    "count": 2,
    "pages": 1
  }
}
```

---

## Create Database

URL: https://developers.cloud66.com/v3/endpoints/databases/#create
Endpoint: POST /stacks/:stack_id/server_groups/:server_group_id/databases
OAuth scope: admin

Creates a new database with the specified name and optionally assigns database users to it.

This operation is performed asynchronously and returns an async action object to track progress. Only works with server groups that support database operations.

**Related models:** Database, Database User, AsyncAction, Server Group

The async action can be monitored using the [Get Stack Action](/v3/endpoints/stacks/action-get) endpoint to track the creation progress.

<ResponseCodes 
  codes={[200, 400, 401, 403, 404]}
  overrides={{
    200: "Success - Returns async action to track database creation",
    400: "Bad Request - Invalid database name or server group does not support database operations", 
    403: "Forbidden - OAuth token lacks required `admin` scope or insufficient permissions",
    404: "Not Found - Stack or server group not found"
  }}
/>

### Parameters

- `stack_id` (string, optional) — Stack ID
- `server_group_id` (string, optional) — Server group ID
- `database_name` (string, optional) — Name for the new database
- `database_user_ids` (string, optional) — Array of database user UIDs to grant access to the new database

### Request body

```json
{
  "database_name": "new_app_db",
  "database_user_ids": ["user_abc123", "user_def456"]
}
```

### Response

```json
{
  "response": {
    "id": 792,
    "status": "queued",
    "action_type": "database_create",
    "resource_type": "database",
    "resource_id": null,
    "started_via": "api",
    "started_at": null,
    "finished_at": null,
    "finished_success": null,
    "finished_message": null,
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-01-15T10:30:00Z"
  }
}
```

---

## Delete Database

URL: https://developers.cloud66.com/v3/endpoints/databases/#delete
Endpoint: DELETE /stacks/:stack_id/server_groups/:server_group_id/databases/:id
OAuth scope: admin

Permanently removes the specified database and all its data. 

<Callout type="warning" title="Data Loss Warning">
This operation cannot be undone and will permanently delete all data in the database. The operation is performed asynchronously and returns an async action object to track progress.
</Callout>

**Related models:** Database, AsyncAction, Server Group

The async action can be monitored using the [Get Stack Action](/v3/endpoints/stacks/action-get) endpoint to track the deletion progress.

<ResponseCodes 
  codes={[200, 400, 401, 403, 404]}
  overrides={{
    200: "Success - Returns async action to track database deletion",
    400: "Bad Request - Server group does not support database operations",
    403: "Forbidden - OAuth token lacks required `admin` scope or insufficient permissions", 
    404: "Not Found - Stack, server group, or database not found"
  }}
/>

### Parameters

- `stack_id` (string, optional) — Stack ID
- `server_group_id` (string, optional) — Server group ID
- `id` (string, optional) — Database UID

### Response

```json
{
  "response": {
    "id": 793,
    "status": "queued",
    "action_type": "database_delete",
    "resource_type": "database",
    "resource_id": "db_abc123",
    "started_via": "api",
    "started_at": null,
    "finished_at": null,
    "finished_success": null,
    "finished_message": null,
    "created_at": "2023-01-15T10:35:00Z",
    "updated_at": "2023-01-15T10:35:00Z"
  }
}
```