# Manage Databases

info
This feature is not enabled on accounts by default. Contact Technical Support or your Customer Success representative to enable it.

This guide explains how to create and delete databases in the Iceberg Catalog using the Database Management API.

## Overview

The Database Management API allows you to create additional databases beyond the default `export` database that is provisioned when your account is first set up. Each database provides an isolated namespace for Iceberg tables that can be queried from Data Workbench (Trino) and accessed from cloud data warehouses (e.g., Databricks, Snowflake).

Only **admin users** can create or delete databases.

## Prerequisites

- Your account must have Iceberg catalog resources provisioned (status: `active`)
- You must use an admin API key (non-admin users receive 403 Forbidden)


## Authentication

For authentication details and API endpoints by site, see [Use Iceberg Catalog Management API](/ja/products/customer-data-platform/composable-publish/use-iceberg-catalog-api).

## Database Naming

When you create a database, you provide a **suffix** (e.g., `analytics`). The system automatically prepends your account prefix to form the full database name:

```
td{account_id}_{site}_{suffix}
```

For example, if your account ID is `10000` on site `us01` and you create a database with suffix `analytics`, the full name will be `td10000_us01_analytics`.

### Naming Rules

The suffix must satisfy the following constraints:

| Rule | Description |
|  --- | --- |
| Pattern | Must match `[a-z][a-z0-9_]{0,63}` |
| First character | Must be a lowercase letter (`a-z`) |
| Allowed characters | Lowercase letters, digits, underscores |
| Maximum length | 64 characters |
| Reserved name | `export` is reserved (the default database) and cannot be used |


**Valid examples:** `analytics`, `data2024`, `my_test_db`, `sales_q1`

**Invalid examples:** `MyDB` (uppercase), `2db` (starts with digit), `_my_db` (starts with underscore), `export` (reserved)

### Quota

Each account can have at most **500** databases.

## API Endpoints

### Create a Database

```
POST /v1/iceberg/catalog/resources/databases
Authorization: TD1 <admin_api_key>
Content-Type: application/json
```

#### Request Body

```json
{
  "db_name": "analytics"
}
```

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `db_name` | string | Yes | Database name suffix. The account prefix is prepended automatically. |


#### curl Example

```sh
curl -X POST "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources/databases" \
  -H "Authorization: TD1 <admin_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"db_name": "analytics"}'
```

#### Response (201 Created)

```json
{
  "db_name": "td10000_us01_analytics"
}
```

The response contains the full database name including the automatically prepended prefix.

#### Error Responses

| Status | Condition |
|  --- | --- |
| 400 | Invalid database name (does not match naming rules), or resources are not in active state |
| 403 | Non-admin user, or write-only API key |
| 404 | Resources are not provisioned for the account |
| 409 | Database already exists, or database quota (500) exceeded |


### Delete a Database

```
DELETE /v1/iceberg/catalog/resources/databases/{db_name}
Authorization: TD1 <admin_api_key>
```

The `{db_name}` path parameter is the **suffix only** (same value you used when creating the database), not the full database name.

#### curl Example

```sh
curl -X DELETE "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources/databases/analytics" \
  -H "Authorization: TD1 <admin_api_key>" \
  -H "Accept: application/json"
```

#### Response (204 No Content)

An empty response body indicates successful deletion.

#### Error Responses

| Status | Condition |
|  --- | --- |
| 400 | Invalid database name, or attempting to delete the reserved `export` database |
| 403 | Non-admin user, or write-only API key |
| 404 | Resources are not provisioned, or the database does not exist |


### Check Current Database Count

Use the Get Resources endpoint to see how many databases your account currently has:

```sh
curl "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources" \
  -H "Authorization: TD1 <admin_api_key>" \
  -H "Accept: application/json"
```

The `db_count` field in the response shows the current number of databases.

## Common Tasks

### Create a database and grant a user access

1. Create the database:


```sh
curl -X POST "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources/databases" \
  -H "Authorization: TD1 <admin_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"db_name": "analytics"}'
```

1. Grant a user permission to the new database (see [Database-Level Access Control for Iceberg Catalog](/ja/products/customer-data-platform/composable-publish/permission-management) for details):


```sh
curl -X PUT "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/permissions" \
  -H "Authorization: TD1 <admin_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "permissions": [
      {
        "resource_type": "DATABASE",
        "resource_names": ["td10000_us01_analytics"],
        "operation": "FULL"
      }
    ]
  }'
```

1. The user can now query the database from Data Workbench:


```sql
SHOW TABLES FROM iceberg.td10000_us01_analytics;
CREATE TABLE iceberg.td10000_us01_analytics.my_table AS SELECT 1 AS id;
```

### Delete a database that is no longer needed

Warning: Deletion is permanent
Before deleting a database, note that:

- All tables within the database will become inaccessible
- Any permissions referencing this database will no longer have effect
- This operation cannot be undone


```sh
curl -X DELETE "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources/databases/analytics" \
  -H "Authorization: TD1 <admin_api_key>" \
  -H "Accept: application/json"
```

### Use wildcard permissions for multiple databases

If a user needs access to all databases (including ones created in the future), use the wildcard `*` in permissions instead of listing each database individually:

```sh
curl -X PUT "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/permissions" \
  -H "Authorization: TD1 <admin_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "permissions": [
      {
        "resource_type": "DATABASE",
        "resource_names": ["*"],
        "operation": "FULL"
      }
    ]
  }'
```

## Important Notes

- The default `export` database cannot be deleted. It is provisioned automatically and managed by the system.
- After creating a database, users need to be granted explicit permissions before they can access it from Data Workbench. Users with wildcard (`*`) permissions will automatically have access.
- Databases are accessible from cloud data warehouses (Databricks, Snowflake) via the table reader IAM role without additional permission configuration, as the reader role has access to all databases under the account prefix.