> ## Documentation Index > Fetch the complete documentation index at: https://docs.rafftechnologies.com/llms.txt > Use this file to discover all available pages before exploring further. # Create database > 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. A free PostgreSQL or MySQL database is usually `running` within 10 seconds. ## 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. - **MySQL**: TLS endpoint on port 3306. Nightly backups plus on-demand backups. - **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. - **ClickHouse** and **Kafka**: see the engine catalog for versions. Kafka clients must trust the `ca_cert` returned by the connection endpoint. ## 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. ## OpenAPI ````yaml POST /api/v1/databases openapi: 3.0.3 info: title: Raff API description: > REST API for managing cloud infrastructure on Raff. ## Authentication Most endpoints require authentication via API key. Catalog endpoints under `/api/v1/public/` are open and require no authentication. ### API Key Authentication Include your API key in the `X-API-Key` header: ``` curl -H "X-API-Key: YOUR_API_KEY" https://api.rafftechnologies.com/api/v1/vms ``` ## Catalog Use the public catalog endpoints to discover available regions, OS templates, and pricing plans before creating resources: - `GET /api/v1/public/regions` — list available regions - `GET /api/v1/public/templates` — list OS templates (use the `id` as `template_id` when creating a VM) - `GET /api/v1/public/pricing/vm` — list VM pricing plans (use the `id` as `pricing_id` when creating a VM) - `GET /api/v1/public/pricing/volume` — volume storage pricing - `GET /api/v1/public/pricing/snapshot` — snapshot storage pricing - `GET /api/v1/public/pricing/backup` — backup storage pricing - `GET /api/v1/public/pricing/ip` — IP address pricing - `GET /api/v1/public/pricing/database` — managed database pricing (plans, high availability, read replicas, extra storage) - `GET /api/v1/public/pricing/kubernetes` — managed Kubernetes pricing (worker node plans, HA control plane, storage nodes) version: 1.0.0 contact: name: Raff Technologies url: https://rafftechnologies.com servers: - url: https://api.rafftechnologies.com description: Production security: - ApiKeyAuth: [] tags: - name: Catalog description: >- Discover available regions, OS templates, and pricing plans. No authentication required. - name: Health description: Health check endpoints - name: Projects description: Organize resources into projects for billing and access control - name: Virtual Machines - name: Kubernetes description: >- Managed Kubernetes clusters — HA control planes, autoscaling node pools, kubeconfig access - name: Functions description: Deploy and manage serverless functions - name: Raff Apps description: >- Push-to-deploy web services, private services, workers, cron jobs, and one-off jobs on the Raff PaaS — with custom domains, environment variables, autoscaling, and per-second billing with spend caps - name: Managed Databases description: >- Fully managed PostgreSQL and Valkey databases with private VPC networking, automatic backups, and metrics - name: Networking description: >- Attach and detach VPCs, floating IPs, and security groups to VM network interfaces - name: Snapshots description: Point-in-time copies of VMs and volumes for quick rollback or cloning - name: Backups description: Scheduled and on-demand VM backups with restore capability - name: Backup Schedules description: Recurring daily or weekly backup schedules attached to a VM - name: SSH Keys description: Manage account-level SSH keys for VM provisioning - name: Members description: Account-level members — invite, list, update role, remove - name: Project Members description: Members of a specific project — same model as Members but project-scoped - name: Roles description: Custom roles bundling account or project permissions - name: Permissions description: List the catalog of permission strings used by roles - name: API Keys description: Create and manage API keys for programmatic access - name: Invitations description: Create and cancel email-based invitations to join the account or a project paths: /api/v1/databases: post: tags: - Managed Databases summary: Create database description: > 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. A free PostgreSQL or MySQL database is usually `running` within 10 seconds. ## 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. - **MySQL**: TLS endpoint on port 3306. Nightly backups plus on-demand backups. - **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. - **ClickHouse** and **Kafka**: see the engine catalog for versions. Kafka clients must trust the `ca_cert` returned by the connection endpoint. ## 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. operationId: createDatabase parameters: - $ref: '#/components/parameters/ProjectIDHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDatabaseRequest' responses: '201': description: Database created (status `pending` while provisioning) content: application/json: schema: type: object properties: success: type: boolean database: $ref: '#/components/schemas/Database' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientBalance' '403': $ref: '#/components/responses/BillingValidationFailed' components: parameters: ProjectIDHeader: name: X-Project-ID in: header required: true description: >- Project ID. Required for all mutating operations (create, delete, power actions, resize). schema: type: string format: uuid schemas: CreateDatabaseRequest: type: object required: - name - plan_id properties: name: type: string description: Display name, unique within the account example: orders-db engine: $ref: '#/components/schemas/DatabaseEngine' engine_version: type: string description: >- Engine major version from the engine catalog. Omit for the default version. example: '16' plan_id: type: integer description: Pricing plan ID from `GET /api/v1/databases/plans` example: 5 storage_gb: type: integer description: >- Storage in GB. Omit to use the plan's included allotment; storage above it bills at $0.12/GB/month. ha_enabled: type: boolean default: false description: Enable high availability (+70% of the plan price) replica_count: type: integer default: 0 description: Read replicas (PostgreSQL only; Valkey rejects a count above 0) region: type: string enum: - us-east default: us-east description: Data center region vpc_id: type: string format: uuid description: >- 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: type: boolean default: false description: Enable public access at create time engine_config: type: object additionalProperties: type: string description: Engine configuration overrides (allowlisted keys only) Database: type: object description: > 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. properties: id: type: string format: uuid description: Unique database identifier database_id: type: string description: Short reference id used in URLs and DNS hostnames, e.g. `a1b2c3d4` project_id: type: string format: uuid description: Project this database belongs to name: type: string description: Display name example: orders-db engine: $ref: '#/components/schemas/DatabaseEngine' engine_version: type: string description: Engine major version example: '16' status: type: string enum: - pending - deploying - running - warning - resizing - restoring - suspended - failed - deleting - deleted description: > Lifecycle status. Creation: `pending` → `deploying` → `running`. `warning` means running with a degraded component. `resizing` and `restoring` mean a scale or in-place restore is in progress. `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: type: string description: Human-readable detail for `warning` and `failed` states region: type: string enum: - us-east description: Data center region example: us-east plan_id: type: integer description: Pricing plan ID (see `GET /api/v1/databases/plans`) example: 5 storage_gb: type: integer description: >- Provisioned storage in GB. Storage above the plan's included allotment bills at $0.12/GB/month. example: 25 ha_enabled: type: boolean description: > High availability — a standby that takes over automatically on failure (Sentinel failover for Valkey). Adds 70% of the plan price. replica_count: type: integer description: Number of read replicas (PostgreSQL only; always 0 for Valkey) example: 0 vpc_id: type: string description: VPC the private endpoint is attached to (empty if not yet connected) public_access: type: boolean description: Whether public access is enabled connection_host: type: string description: Private endpoint hostname, resolvable inside the attached VPC example: a1b2c3d4.db.raffusercloud.com connection_port: type: integer description: >- Private endpoint port. PostgreSQL: 6432 pooled (PgBouncer, transaction mode), 5432 direct. Valkey: 6379 (TLS). example: 6432 billing_type: type: string enum: - payg - subscription description: Billing type for this database example: payg subscription_id: type: string description: Subscription ID if billing_type is subscription (empty otherwise) price_per_hour: type: number description: Hourly billing rate in USD example: 0.010945 monthly_price: type: number description: Monthly price in USD example: 7.99 public_port: type: integer description: > 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. PostgreSQL is also reachable on the standard ports 6543 (pooled) and 5432 (direct) of `public_dns_hostname`. example: 25060 public_dns_hostname: type: string description: Public endpoint hostname (empty when public access is off) example: a1b2c3d4.public.db.raffusercloud.com public_allowlist: type: array items: type: string description: >- Source CIDRs allowed on the public endpoint. Empty = allow all sources. example: - 203.0.113.0/24 is_free: type: boolean description: >- True for a free-tier database. Free databases pause after 7 days without connections. suspended_at: type: string description: >- When a free-tier database was paused for idleness, RFC 3339 (empty when not paused) created_at: type: string format: date-time updated_at: type: string format: date-time DatabaseEngine: type: string enum: - postgres - mysql - valkey - clickhouse - kafka description: >- Database engine identifier. Defaults to `postgres` on create; the live catalog (including availability and versions) is `GET /api/v1/databases/engines`. example: postgres Error: type: object properties: error: type: string message: type: string BillingError: type: object description: >- Billing validation error response. Returned when the account is not in good standing for paid operations. required: - error - reason properties: error: type: string example: Billing validation failed message: type: string example: Payment failed. Please update your payment method. reason: type: string description: > Machine-readable reason code: - `banned` — account has been suspended - `failed` — last payment failed; balance top-up needed - `no_billing_customer` — billing has not been set up for this account enum: - banned - failed - no_billing_customer responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' InsufficientBalance: description: > Account balance is insufficient for this operation. Top up the balance and retry. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Payment Required message: Insufficient balance for subscription BillingValidationFailed: description: | 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 content: application/json: schema: $ref: '#/components/schemas/BillingError' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication. Each key is bound to a specific account. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.