create-db

create-db

create-db is an open-source CLI tool and library that provisions temporary Prisma Postgres databases with a single command.

Each database is available for 24 hours by default. To keep the database permanently, you can claim it for free using the URL displayed in the output.

This tool is designed for developers who need a fast way to test, prototype, or integrate Prisma Postgres without manual setup or creating an account.

Installation and Usage

No installation required. Simply run:

npx create-db@latest

You can also use these aliases:

npx create-pg@latest
npx create-postgres@latest

CLI Usage

Commands

npx create-db [create]   # Create a new database (default command)
npx create-db regions    # List available regions

Options

Flag	Alias	Description
--region <region>	-r	AWS region for the database
--interactive	-i	Interactive mode to select a region
--json	-j	Output machine-readable JSON
--env <path>	-e	Write DATABASE_URL and CLAIM_URL to specified .env file
--help	-h	Show help message
--version		Show version

Available Regions

• ap-southeast-1 - Asia Pacific (Singapore)
• ap-northeast-1 - Asia Pacific (Tokyo)
• eu-central-1 - Europe (Frankfurt)
• eu-west-3 - Europe (Paris)
• us-east-1 - US East (N. Virginia)
• us-west-1 - US West (N. California)

Examples

# Create database in auto-detected nearest region
npx create-db

# Create database in a specific region
npx create-db --region eu-west-3
npx create-db -r us-east-1

# Interactive region selection
npx create-db --interactive
npx create-db -i

# Output as JSON (useful for scripting)
npx create-db --json
npx create-db -j

# Write connection string to .env file
npx create-db --env .env
npx create-db -e .env.local

# Combine flags
npx create-db -r eu-central-1 -j
npx create-db -i -e .env

# List available regions
npx create-db regions

JSON Output

When using --json, the output includes:

{
  "success": true,
  "connectionString": "postgresql://user:pass@host:5432/postgres?sslmode=require",
  "claimUrl": "https://create-db.prisma.io/claim?projectID=...",
  "deletionDate": "2025-12-13T12:00:00.000Z",
  "region": "us-east-1",
  "name": "2025-12-12T12:00:00.000Z",
  "projectId": "proj_..."
}

Environment File Output

When using --env, the following variables are appended to the specified file:

DATABASE_URL="postgresql://user:pass@host:5432/postgres?sslmode=require"
CLAIM_URL="https://create-db.prisma.io/claim?projectID=..."

Programmatic API

You can also use create-db as a library in your Node.js applications:

npm install create-db
# or
bun add create-db

create(options?)

Create a new Prisma Postgres database programmatically.

import { create } from "create-db";

const result = await create({ region: "us-east-1" });

if (result.success) {
  console.log(`Connection string: ${result.connectionString}`);
  console.log(`Claim URL: ${result.claimUrl}`);
  console.log(`Expires: ${result.deletionDate}`);
} else {
  console.error(`Error: ${result.message}`);
}

Options

Option	Type	Description
region	RegionId	AWS region for the database (optional, defaults to us-east-1)
userAgent	string	Custom user agent string for tracking (optional)

regions()

List available Prisma Postgres regions.

import { regions } from "create-db";

const availableRegions = await regions();
console.log(availableRegions);
// [{ id: "us-east-1", name: "US East (N. Virginia)", status: "available" }, ...]

Type Guards

import { create, isDatabaseSuccess, isDatabaseError } from "create-db";

const result = await create();

if (isDatabaseSuccess(result)) {
  // result is DatabaseResult
  console.log(result.connectionString);
}

if (isDatabaseError(result)) {
  // result is DatabaseError
  console.error(result.message);
}

Types

import type {
  Region,
  RegionId,
  CreateDatabaseResult,
  DatabaseResult,
  DatabaseError,
  ProgrammaticCreateOptions,
} from "create-db";

// RegionId is a union type of available regions
type RegionId = "ap-southeast-1" | "ap-northeast-1" | "eu-central-1" | "eu-west-3" | "us-east-1" | "us-west-1";

// DatabaseResult (success)
interface DatabaseResult {
  success: true;
  connectionString: string | null;
  claimUrl: string;
  deletionDate: string;
  region: string;
  name: string;
  projectId: string;
  userAgent?: string;
}

// DatabaseError (failure)
interface DatabaseError {
  success: false;
  error: string;
  message: string;
  raw?: string;
  details?: unknown;
  status?: number;
}

// CreateDatabaseResult is DatabaseResult | DatabaseError

Region Validation with Zod

import { RegionSchema } from "create-db";

// Validate region input
const result = RegionSchema.safeParse("us-east-1");
if (result.success) {
  console.log("Valid region:", result.data);
}

Claiming a Database

When you create a database, it is temporary and will be deleted after 24 hours.

The output includes a claim URL that allows you to keep the database permanently for free.

What claiming does:

• Moves the database into your Prisma Data Platform account
• Prevents it from being auto-deleted
• Lets you continue using the database as a long-term instance

Next Steps

• Refer to the Prisma Postgres documentation for more details.