Manage Databases

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

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.

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

For authentication details and API endpoints by site, see Use Iceberg Catalog Management API.

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.

The suffix must satisfy the following constraints:

Valid examples: analytics, data2024, my_test_db, sales_q1

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

Each account can have at most 500 databases.

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

{
  "db_name": "analytics"
}

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"}'

{
  "db_name": "td10000_us01_analytics"
}

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

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 -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"

An empty response body indicates successful deletion.

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

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.

1. Create the database:

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"}'

2. Grant a user permission to the new database (see Database-Level Access Control for Iceberg Catalog for details):

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"
      }
    ]
  }'

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

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

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"

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:

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"
      }
    ]
  }'

• 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.