Sign in
Databases

Create a new PostgreSQL database

Changed on

Creates a PostgreSQL database in the project. Each project can hold 1 database on HOBBY and up to 10,000 on SUPERAGENT. Requests over the plan's cap return 403.

post/projects/{id}/databases

Request

  • Base URL: https://api.volcano.dev
  • URL: https://api.volcano.dev/projects/{id}/databases
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

idstring uuid required

Project ID

Request body

namestring required

Database name (must be unique within project)

regionstring required

Region for database hosting, such as us-east-1. The accepted values are the regions this environment runs in, so read them from GET /databases/regions rather than hardcoding a list. A region the environment does not offer is rejected with 400. Region IDs issued by earlier versions of the API are still accepted.

pg_version'16' | '17' | '18' required

PostgreSQL major version. GET /databases/postgres-versions lists the versions this environment accepts; local mode accepts only the version its server runs. Any other value is rejected with 400.

database_type'volcano-db-xs' | 'volcano-db-s' | 'volcano-db-m' | 'volcano-db-l' | 'volcano-db-xl' | 'volcano-db-2xl'

Compute size tier (optional, defaults to volcano-db-xs). Determines autoscaling limits for the database.

Example request

{
  "name": "my_database",
  "region": "us-east-1",
  "pg_version": "18",
  "database_type": "volcano-db-xs"
}

Response

Database created (provisioning)

idstring uuid required
project_idstring uuid required
namestring required

Database name

status'provisioning' | 'active' | 'failed' | 'restoring' | 'deleting' required

Database status. restoring means a restore is replacing the database's data: it does not accept connections, and the operations that would race the restore are rejected until it finishes. Its branches keep serving throughout.

provisioning_started_atstring date-time

Timestamp when the current provisioning phase started

connection_stringstring

Secure PostgreSQL connection URI for your database.

The database is identified by the globally-unique username (volcano_client_{database_id}) already in this URI; the application_name parameter only selects the access mode:

  • volcano_full_access — Full admin access (DDL, migrations)
  • volcano_user_access:{user_id} — User impersonation (RLS enforced)
  • volcano_user_access — Anonymous access (anon role, RLS enforced)
regionstring

Region where the database is hosted

pg_versionstring

PostgreSQL major version

database_type'volcano-db-xs' | 'volcano-db-s' | 'volcano-db-m' | 'volcano-db-l' | 'volcano-db-xl' | 'volcano-db-2xl'

Database size tier that determines available RAM and scaling limits.

storage_bytesinteger

Latest observed storage for this database, in bytes: its own on-disk size, plus what each branch has diverged from it, plus what its backups cost to hold. This is the figure the storage allowance is enforced against, and the stats endpoint breaks it down. A point-in-time gauge recorded by a background pass, so it may be absent until the database has been sampled, and it can trail the stats endpoint's current_storage_bytes, which measures on request. Summing the latest samples for every database in a project produces the project's "Database Storage (Bytes)" usage gauge. Populated on database list responses; single-database responses omit it.

last_invoked_atstring date-time

Most recent request timestamp for this database

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "region": "us-east-1",
  "pg_version": "18",
  "database_type": "volcano-db-xs"
}

Changes

  • f03633d398ecRevision changes
    • ▲

      removed the enum value 15 of the request property

  • 23e7875e7c4cRevision changes
    • ○

      the endpoint scheme security ProjectAccessToken was added to the API

    • ○

      added the new 17 enum value to the request property

    • ○

      added the new 18 enum value to the request property