Creating Databases

Provision PostgreSQL databases.

List Available Regions

Get the list of available AWS regions for database provisioning:

curl https://api.volcano.dev/databases/regions

Response:

[
  {
    "id": "aws-us-east-1",
    "name": "AWS US East 1 (N. Virginia)"
  },
  {
    "id": "aws-us-east-2",
    "name": "AWS US East 2 (Ohio)"
  },
  {
    "id": "aws-eu-central-1",
    "name": "AWS Europe Central 1 (Frankfurt)"
  }
]

This is a public endpoint (no authentication required).

List Available PostgreSQL Versions

Get the list of supported PostgreSQL versions:

curl https://api.volcano.dev/databases/postgres-versions

Response:

[
  {
    "version": "16",
    "name": "PostgreSQL 16",
    "recommended": true,
    "default": true
  },
  {
    "version": "15",
    "name": "PostgreSQL 15"
  }
]

This is a public endpoint (no authentication required).

Create a Database

curl -X POST https://api.volcano.dev/projects/PROJECT_ID/databases \
  -H "Authorization: Bearer PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main_db",
    "region": "aws-us-east-1",
    "pg_version": "16",
    "database_type": "volcano-db-xs"
  }'

Request Body:

name (required): Database name (lowercase, underscores)
region (optional): AWS region ID (from /databases/regions)
pg_version (optional): PostgreSQL version (from /databases/postgres-versions)
database_type (optional): Compute size tier (default: volcano-db-xs)

Response:

{
  "id": "db-uuid",
  "database_name": "main_db",
  "database_type": "volcano-db-xs",
  "status": "provisioning",
  "region": "aws-us-east-1",
  "pg_version": "16",
  "created_at": "2024-01-01T00:00:00Z"
}

Status progression:

provisioning - Being created (5-10 seconds)
active - Ready to use
failed - Creation failed

Database Types

Choose a size based on your workload:

Type	RAM	Use Case
`volcano-db-xs`	Up to ~1GB	Development, small apps
`volcano-db-s`	Up to ~4GB	Production-ready, light traffic
`volcano-db-m`	Up to ~8GB	Medium traffic applications
`volcano-db-l`	Up to ~16GB	High traffic, larger datasets
`volcano-db-xl`	Up to ~32GB	Heavy workloads
`volcano-db-2xl`	Up to ~64GB	Enterprise-scale

Serverless Scaling: All databases automatically scale to zero when idle (after 3 minutes of inactivity) and scale up on demand within their type's limits.

Update Database Type

Change the compute size of an existing database:

curl -X PATCH https://api.volcano.dev/projects/PROJECT_ID/databases/DB_ID/type \
  -H "Authorization: Bearer PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "database_type": "volcano-db-s"
  }'

Warning: Changing the database type will briefly interrupt database connections while the compute endpoint is reconfigured.

Get Database Details

curl https://api.volcano.dev/projects/PROJECT_ID/databases/DB_ID \
  -H "Authorization: Bearer PLATFORM_TOKEN"

When status is active, includes connection_string:

{
  "id": "abc-123-456-789",
  "database_name": "main_db",
  "status": "active",
  "connection_string": "postgresql://volcano_client_11111111-1111-1111-1111-111111111111:vpg_abc123@database.volcano.dev:5432/myapp_main?sslmode=require&application_name=volcano_full_access",
  "region": "aws-us-east-1",
  "pg_version": "16",
  "created_at": "2024-01-01T00:00:00Z"
}

Use this connection_string to connect from your functions or applications. The username and password are Volcano-managed client credentials. The password starts with vpg_; Neon credentials are never returned by the API.

Using the Connection String

In functions (automatic):

const { Pool } = require('pg');
const pool = new Pool({
  connectionString: process.env.DATABASE_URL  // Auto-set
});

Direct connection:

psql "postgresql://user:pass@database.volcano.dev:5432/db"

Auth Helpers (Auto-Installed)

When the database is created, Volcano automatically installs:

auth.uid()     -- Get current user ID
auth.email()   -- Get current user email
auth.role()    -- Get current user role

Verify:

psql $CONNECTION_STRING -c "SELECT auth.uid();"

See Auth Helpers for usage.

Multiple Databases

All databases in a project share infrastructure:

Project "my-app"
  ├─ Database: my_app_main
  ├─ Database: my_app_analytics
  └─ Database: my_app_staging

This is cost-effective (shared infrastructure).

List Databases

curl https://api.volcano.dev/projects/PROJECT_ID/databases \
  -H "Authorization: Bearer PLATFORM_TOKEN"

Delete a Database

curl -X DELETE https://api.volcano.dev/projects/PROJECT_ID/databases/DB_ID \
  -H "Authorization: Bearer PLATFORM_TOKEN"

This permanently deletes the database. Cannot be undone.

Reset Password

curl -X POST https://api.volcano.dev/projects/PROJECT_ID/databases/DB_ID/reset-password \
  -H "Authorization: Bearer PLATFORM_TOKEN"

Response:

{
  "message": "Password reset successful",
  "role_name": "volcano_client_11111111-1111-1111-1111-111111111111",
  "new_password": "vpg_new_secure_password",
  "connection_string": "postgresql://volcano_client_11111111-1111-1111-1111-111111111111:vpg_new_secure_password@database.volcano.dev:5432/main_db?sslmode=require&application_name=volcano_full_access"
}

Update your functions' DATABASE_URL with the new connection string. The old Volcano password stops working after reset. The internal Neon owner password is not rotated and is never exposed to clients.

Creating Databases

List Available Regions

List Available PostgreSQL Versions

Create a Database

Database Types

Update Database Type

Get Database Details

Using the Connection String

Auth Helpers (Auto-Installed)

Multiple Databases

List Databases

Delete a Database

Reset Password

See Also

On this page