---
title: "Create database"
method: POST
path: "/api/v1/databases"
tags: ["Managed Databases"]
---

# Create database

`POST /api/v1/databases`

Create a managed database. Provisioning is asynchronous — the database is created in status `pending` and moves through `deploying` to `running`; poll `GET /api/v1/databases/{database_id}` for progress.

## Networking

Databases live on private VPC networking by default. Set `vpc_id` to place the private endpoint (`{database_id}.db.raffusercloud.com`) inside an existing VPC, or attach a VPC later via `POST /api/v1/databases/{database_id}/vpc`. Public access is optional and off by default. TLS is always required.

## Engines

- **PostgreSQL** — pooled endpoint on port 6432 (PgBouncer, transaction mode) plus a direct endpoint on 5432. Nightly base backup with continuous WAL archiving for point-in-time restore.
- **Valkey** — single TLS endpoint on port 6379. Nightly RDB snapshots plus on-demand snapshots. No read replicas — high availability adds a standby with automatic Sentinel failover.

## Pricing

The plan sets the base price. High availability adds 70% of the tier price; storage above the tier allotment is $0.12/GB/month. See `GET /api/v1/public/pricing/database` for the full catalog.

## Headers

- `X-Project-ID` string, uuid, required

## Request body

- CreateDatabaseRequest
  - `name` string, required — Display name, unique within the account
  - `engine` 'postgres' | 'mysql' | 'valkey' | 'clickhouse' | 'kafka' — Database engine identifier. Defaults to `postgres` on create; the live catalog (including availability and versions) is `GET /api/v1/databases/engines`.
  - `engine_version` string — Engine major version from the engine catalog. Omit for the default version.
  - `plan_id` integer, required — Pricing plan ID from `GET /api/v1/databases/plans`
  - `storage_gb` integer — Storage in GB. Omit to use the plan's included allotment; storage above it bills at $0.12/GB/month.
  - `ha_enabled` boolean — Enable high availability (+70% of the plan price)
  - `replica_count` integer — Read replicas (PostgreSQL only; Valkey rejects a count above 0)
  - `region` 'us-east' — Data center region
  - `vpc_id` string, uuid — VPC to place the private endpoint in. Omit to create without VPC connectivity and attach one later via `POST /api/v1/databases/{database_id}/vpc`.
  - `public_access` boolean — Enable public access at create time
  - `engine_config` object — Engine configuration overrides (allowlisted keys only)

## Response `201`

Database created (status `pending` while provisioning)

- object
  - `success` boolean
  - `database` Database — A managed database instance. The private endpoint `{database_id}.db.raffusercloud.com` lives inside the attached VPC; public access is optional. TLS is always required.
    - `id` string, uuid — Unique database identifier
    - `database_id` string — Short reference id used in URLs and DNS hostnames, e.g. `a1b2c3d4`
    - `project_id` string, uuid — Project this database belongs to
    - `name` string — Display name
    - `engine` 'postgres' | 'mysql' | 'valkey' | 'clickhouse' | 'kafka' — Database engine identifier. Defaults to `postgres` on create; the live catalog (including availability and versions) is `GET /api/v1/databases/engines`.
    - `engine_version` string — Engine major version
    - `status` 'pending' | 'deploying' | 'running' | 'warning' | 'suspended' | 'failed' | 'deleting' | 'deleted' — Lifecycle status. Creation: `pending` → `deploying` → `running`. `warning` means running with a degraded component; `suspended` means a free-tier database paused for idleness (resume any time — data is kept); `failed` means provisioning or a scale operation failed.
    - `status_message` string — Human-readable detail for `warning` and `failed` states
    - `region` 'us-east' — Data center region
    - `plan_id` integer — Pricing plan ID (see `GET /api/v1/databases/plans`)
    - `storage_gb` integer — Provisioned storage in GB. Storage above the plan's included allotment bills at $0.12/GB/month.
    - `ha_enabled` boolean — High availability — a standby that takes over automatically on failure (Sentinel failover for Valkey). Adds 70% of the plan price.
    - `replica_count` integer — Number of read replicas (PostgreSQL only; always 0 for Valkey)
    - `vpc_id` string, uuid — VPC the private endpoint is attached to (empty if not yet connected)
    - `public_access` boolean — Whether public access is enabled
    - `connection_host` string — Private endpoint hostname, resolvable inside the attached VPC
    - `connection_port` integer — Private endpoint port. PostgreSQL: 6432 pooled (PgBouncer, transaction mode), 5432 direct. Valkey: 6379 (TLS).
    - `billing_type` 'payg' | 'subscription' — Billing type for this database
    - `subscription_id` string, uuid — Subscription ID if billing_type is subscription
    - `price_per_hour` number — Hourly billing rate in USD
    - `monthly_price` number — Monthly price in USD
    - `public_port` integer — Public port from the reserved range 25060–26060; `0` when public access is off. For PostgreSQL, `public_port` is the pooled endpoint and `public_port + 1` is the direct endpoint.
    - `public_dns_hostname` string — Public endpoint hostname (empty when public access is off)
    - `public_allowlist` string[] — Source CIDRs allowed on the public endpoint. Empty = allow all sources.
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication required
- `402` — Account balance is insufficient for this operation. Top up the balance and retry.
- `403` — Billing validation failed. The account is not in good standing. Check the `reason` field: - `banned` — account suspended - `failed` — last payment failed; top up the account balance - `no_billing_customer` — billing not set up

---

[API](https://skmtc.dev/rafftechnologies/apis/raff-api.md) · [All operations](https://skmtc.dev/rafftechnologies/apis/raff-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rafftechnologies/raff-api/revisions/2f4df56be77c/schema)