create-db
v1.3.2
Published
Instantly create a temporary Prisma Postgres database with one command, then claim and persist it in your Prisma Data Platform project when ready.
Maintainers
Readme
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@latestYou can also use these aliases:
npx create-pg@latest
npx create-postgres@latestCLI Usage
Commands
npx create-db [create] # Create a new database (default command)
npx create-db regions # List available regionsOptions
| 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 |
| --ttl <duration> | -t | Custom database TTL (30m, 1h ... 24h) |
| --copy | -c | Copy connection string to clipboard |
| --quiet | -q | Output only the connection string (the claim URL goes to stderr) |
| --open | -o | Open claim URL in browser |
| --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
# Set custom TTL
npx create-db --ttl 1h
npx create-db -t 12h
# Copy connection string to clipboard
npx create-db --copy
npx create-db -c
# Only print connection string
npx create-db --quiet
npx create-db -q
# Open claim URL in browser
npx create-db --open
npx create-db -o
# Combine flags
npx create-db -r eu-central-1 -j
npx create-db -i -e .env
npx create-db -t 24h -c -o
# List available regions
npx create-db regions
# List available regions as JSON
npx create-db regions --jsonJSON Output
When using --json with create, 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_...",
"nextStep": "The database is deleted at 2025-12-13T12:00:00.000Z unless the user claims it, which keeps it for free. Give the user this claim URL: https://create-db.prisma.io/claim?projectID=..."
}nextStep is for agents and scripts that run create-db for someone else: the database is deleted at deletionDate unless that person opens claimUrl and claims it.
Add --env <path> to also write DATABASE_URL and CLAIM_URL to that file. If the file can't be written, the JSON is still printed and the command exits with code 1.
When using --json with regions, the output is an array of region objects:
[
{
"id": "us-east-1",
"name": "US East (N. Virginia)",
"status": "available"
}
]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=..."The CLI also prints the claim URL and deletion time, so the person running it can claim the database before it is deleted.
Programmatic API
You can also use create-db as a library in your Node.js applications:
npm install create-db
# or
bun add create-dbcreate(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) |
| ttl | string | TTL string (30m, 1h ... 24h) |
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 | DatabaseErrorRegion 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.
