Database Provisioning

Createst provides fully managed PostgreSQL databases that you can provision, manage, and connect to your projects — all from within the platform. Each database is a serverless Postgres instance with automatic scaling, connection pooling, and instant branching for preview deployments.

Overview

Every Createst database is a fully managed, serverless PostgreSQL instance. Key properties:

• Serverless — Compute scales to zero when idle and wakes up on the first connection. You only pay for what you use.
• Instant branching — Create copy-on-write branches of your database in seconds. Branches share storage with the parent, so they're almost free until data diverges.
• Connection pooling — Every database includes a built-in PgBouncer connection pooler. Use the pooled connection string for web applications.
• Encrypted at rest — Connection strings and passwords are AES-256-GCM encrypted before storage. They're decrypted only when you request them.
• Automatic cleanup — Preview database branches are automatically deleted when their deployment is removed. An hourly cleanup job catches any orphaned branches.

Creating a Database

From the UI

1. Navigate to Settings in the left sidebar
2. Click Databases in the Settings menu
3. Click Create Database
4. Enter a name for your database (must be unique within your account)
5. Select a region (default: AWS US East - Ohio)
6. Click Create

The database begins provisioning immediately. Status updates appear in real time. Most databases become active within 10-15 seconds.

From the API

POST /api/databases
Content-Type: application/json

{
  "name": "my-app-db",
  "region": "aws-us-east-2"
}

Optional fields:

Database Lifecycle

Each database has a status that reflects its current state:

Provisioning Status (SSE)

You can subscribe to real-time provisioning updates via Server-Sent Events:

GET /api/databases/:id/provisioning-status

The stream emits JSON events every 2 seconds:

{"status": "PROVISIONING", "done": false}
{"status": "ACTIVE", "done": true}

The stream ends when status reaches ACTIVE, FAILED, or after 60 seconds.

Retrying Failed Provisioning

If a database enters the FAILED state, you can retry:

• UI: Click the Retry button on the database card
• API: POST /api/databases/:id/retry

This resets the status to PROVISIONING and polls the infrastructure again.

Deleting a Database

• UI: Click Delete on the database card (with confirmation)
• API: DELETE /api/databases/:id

Deletion is permanent. The underlying infrastructure is destroyed asynchronously. Associated database branches are also cleaned up.

Connection Strings

Each database provides two connection strings:

Pooled (Recommended)

The pooled connection uses a built-in PgBouncer connection pooler. Use this for web applications — it handles connection multiplexing and prevents exhausting the connection limit.

postgresql://user:password@ep-cool-name-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require

Direct

The direct connection bypasses the pooler and connects straight to the Postgres instance. Use this for:

• Database migrations (e.g., prisma migrate deploy)
• Long-running queries
• LISTEN/NOTIFY
• Tools that manage their own connection pool

postgresql://user:password@ep-cool-name.us-east-2.aws.neon.tech/neondb?sslmode=require

Viewing Connection Strings

• UI: Click Connection String on any active database card. A modal shows both pooled and direct strings with copy buttons.
• API: GET /api/databases/:id/connection-string

Every time you view a connection string, an audit log entry is created.

Compute and Scaling

Databases use a serverless compute model measured in Compute Units (CU):

How Autoscaling Works

1. When a connection arrives, compute starts at minComputeCU
2. Under load, compute scales up automatically (up to maxComputeCU)
3. When load decreases, compute scales back down
4. After suspendTimeoutSeconds of zero activity, compute suspends entirely
5. The next connection wakes compute automatically (cold start ~500ms)

Updating Compute Settings

PATCH /api/databases/:id
Content-Type: application/json

{
  "minComputeCU": 0.5,
  "maxComputeCU": 8,
  "suspendTimeoutSeconds": 1800
}

Changes are applied to the underlying compute endpoint asynchronously.

Preview Databases (Branching)

The most powerful database feature is instant branching for preview deployments. When you push a commit and Createst creates a preview deployment, it can automatically create a database branch — a copy-on-write clone of your production database.

How It Works

1. You configure a source database for your project (see Project Database Configuration)
2. When a preview deployment is triggered (e.g., by a git push), Createst:
   • Creates a database branch named preview-{commit-sha} from the source database's default branch
   • Fetches the branch's connection URI
   • Injects it as an environment variable (default: DATABASE_URL) into the preview deployment container
3. Your preview app boots with its own isolated database that contains a snapshot of production data
4. When the preview deployment is deleted, the database branch is automatically cleaned up

Why This Matters

• Instant: Branches are created in seconds using copy-on-write — no data copying
• Isolated: Each preview deployment gets its own database. Schema changes, test data, and migrations in one preview don't affect others or production
• Cost-effective: Branches share storage with the parent. You only pay for data that diverges
• Automatic: No manual setup — branches are created and destroyed with the deployment lifecycle

Branch Lifecycle

Orphan Branch Cleanup

If a deployment is deleted through an unexpected path (crash, force-delete, etc.), its database branch might be left behind. A background cleanup job runs every hour and:

1. Finds all database branches linked to deployments
2. Checks if the linked deployment still exists
3. Deletes any branches whose deployments are gone
4. Logs each cleanup action in the audit log

Project Database Configuration

To enable automatic preview database branching for a project, configure a Project Database Config:

From the API

PUT /api/databases/projects/:projectKey/database-config
Content-Type: application/json

{
  "sourceDatabaseId": "clxx1234...",
  "previewMinComputeCU": 0.25,
  "previewMaxComputeCU": 1,
  "previewSuspendTimeoutSeconds": 300,
  "previewMaxStorageGB": 5,
  "autoCreateBranchForPreview": true,
  "autoDeleteBranchOnCleanup": true,
  "envVarName": "DATABASE_URL"
}

Configuration Fields

Reading the Config

GET /api/databases/projects/:projectKey/database-config

Returns null if no config exists.

Removing the Config

DELETE /api/databases/projects/:projectKey/database-config

Production Databases

For production workloads, the database you create in Createst is your production database. There's no separate "production mode" — the same database serves all environments:

• Production: Your app connects using the database's connection string (pooled recommended)
• Preview/Staging: Automatic branches give each preview its own isolated copy of the production data
• Development: You can connect directly from your local machine using the direct connection string

Recommended Setup

1. Create one database per application (e.g., my-saas-db)
2. Configure Project Database Config to enable preview branching
3. Set compute limits appropriate for your production load:
   • Small apps: minComputeCU: 0.25, maxComputeCU: 2
   • Medium apps: minComputeCU: 0.5, maxComputeCU: 4
   • High-traffic: minComputeCU: 1, maxComputeCU: 8
4. Use pooled connection for your web app, direct connection for migrations
5. Set suspendTimeoutSeconds based on your traffic pattern:
   • Always-on: 0 (never suspend)
   • Light traffic with occasional gaps: 3600 (1 hour)
   • Dev/staging: 300 (5 minutes)

Connection in Your App

In your application code:

// The connection string is available as an env var
const connectionString = process.env.DATABASE_URL;

// For Prisma
// In schema.prisma:
// datasource db {
//   provider = "postgresql"
//   url      = env("DATABASE_URL")
// }

// For raw pg
import pg from 'pg';
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

For preview deployments, the DATABASE_URL (or your configured envVarName) is automatically set to the branch's connection string. No code changes needed.

Password Rotation

You can rotate the database password at any time:

• API: POST /api/databases/:id/rotate-password

This generates a new password and updates the encrypted connection strings stored in Createst. The response includes the new password.

Important: After rotation, you must update any external services that use the old password. Applications running on Createst preview deployments will automatically use the new credentials on their next deployment.

Usage and Billing

Database usage is metered along these dimensions:

Viewing Usage

• UI: Available in the database detail view
• API: GET /api/databases/:id/usage?days=30

Usage records are broken down by period (hourly granularity) with cost estimates in cents:

{
  "success": true,
  "data": [
    {
      "periodStart": "2026-04-10T00:00:00Z",
      "periodEnd": "2026-04-10T01:00:00Z",
      "computeTimeSeconds": 3600,
      "activeTimeSeconds": 3200,
      "writtenDataBytes": 1048576,
      "storageSizeBytes": 52428800,
      "computeCostCents": 12,
      "storageCostCents": 3,
      "totalCostCents": 15
    }
  ]
}

Cost Model

• Compute: Billed per CU-hour of active compute
• Storage: Billed per GB-month of stored data
• Branching: Branches use copy-on-write — you only pay for data that diverges from the parent

There is no free tier. All usage is billed from the first CU-hour. This keeps the pricing simple and predictable.

Regions

Choose the region closest to your application servers for lowest latency:

The region is set at database creation time and cannot be changed. To move to a different region, create a new database and migrate your data.

Admin Dashboard

Platform administrators have access to a comprehensive database management dashboard at Admin > Databases. It includes four tabs:

Summary Tab

Platform-wide aggregates:

• Total databases, active databases, suspended databases
• Total branches across all users
• Aggregate compute and storage costs
• Per-user breakdown (user name, email, database count)

Databases Tab

Searchable, filterable list of all databases across the platform:

• Filter by status (Active, Provisioning, Suspended, Failed)
• Search by database name
• View owner, region, compute settings, branch count
• Force-delete any database (admin only)

Keys Tab

Monitoring and management of the platform's API key configuration:

• Which key is currently active (primary vs fallback)
• Whether primary and fallback keys are configured
• Fallback usage count and last fallback usage timestamp
• Swap Keys button for zero-downtime key rotation

Audit Log Tab

Complete audit trail of all database operations across the platform:

• Filterable by action, user, or database
• Tracks: creation, deletion, connection string views, password rotations, settings changes, orphan cleanups, retry attempts

API Key Management (Admins)

The platform uses API keys to communicate with the database infrastructure. Admins can manage these keys:

Primary + Fallback Key Architecture

Two API keys can be configured simultaneously:

1. Primary Key — Used for all API calls by default
2. Fallback Key — Automatically used if the primary key returns a 401 or 403 error

This enables zero-downtime key rotation:

1. Set the new key as the fallback
2. Monitor the admin Keys tab — fallback usage count shows if the primary is failing
3. When ready, click Swap Keys to promote the fallback to primary
4. Remove the old key from the fallback slot

Key Status API

GET /api/admin/databases/neon/status

Response:

{
  "success": true,
  "data": {
    "primaryKeyConfigured": true,
    "fallbackKeyConfigured": false,
    "activeKey": "primary",
    "fallbackUsageCount": 0,
    "lastFallbackUsage": null
  }
}

Swap Keys API

POST /api/admin/databases/neon/swap-keys

Instantly promotes the fallback key to primary and demotes the old primary to fallback.

Audit Log

Every database operation is logged in an immutable audit trail. Logged actions include:

Each entry records:

• Timestamp
• User who performed the action
• Database and branch involved (if applicable)
• Success/failure status
• Error message (if failed)
• Additional details as JSON

API

# Admin: View all audit logs (paginated, filterable)
GET /api/admin/databases/audit-log?action=DATABASE_CREATE&limit=50&offset=0

Environment Variables

Platform Configuration

Security Notes

• The API key is never exposed to executor pods or user code. It exists only on the control plane.
• Connection strings and passwords are encrypted with AES-256-GCM before storage. They are decrypted only at the moment of use or when explicitly requested by the database owner.

Injected Into Deployments

When preview branching is enabled, the following environment variable is automatically injected into preview deployment containers:

This variable is set per-deployment and contains the branch-specific connection string, so each preview gets its own isolated database.

API Reference

All endpoints require authentication. Admin endpoints additionally require the platform admin role.

User Endpoints

Admin Endpoints