get-db

get-db

CLI to help you hit the ground running without any sign-up. Instantiate a database with a single-command!

CLI Usage

The CLI provides a default referrer value, so the --ref flag is optional.

Package Manager	Command
npm	npx get-db
pnpm	pnpx get-db
yarn	yarn dlx get-db
bun	bunx get-db
deno	deno run npm:get-db

npx get-db [options]

Options:

• -y, --yes Use defaults, skip prompts
• -e, --env Path to .env file (default: ./.env)
• -k, --key Env key for connection string (default: DATABASE_URL)
• -p, --prefix Prefix for public env vars (default: PUBLIC_)
• -r, --ref Referrer identifier for tracking (default: npm:get-db/cli)
• -s, --seed Path to SQL file to execute after database creation
• -L, --logical-replication Enable logical replication (default: false)
• -h, --help Show help

SDK/API Usage

Import the SDK:

import { instantPostgres } from "get-db/sdk";

Create a claimable Neon Postgres database and save credentials to your .env:

await instantPostgres({
	referrer: "your-cli-package-name", // REQUIRED
	dotEnvFile: ".env",
	dotEnvKey: "DATABASE_URL",
	envPrefix: "PUBLIC_",
	settings: {
		logicalReplication: false, // Enable logical replication
	},
	// This referrer parameter helps us understand where usage comes from.
	// If you're publishing a library, we'd love that you re-expose a
	// referrer parameter in your lib and set this to `npm:your-lib-package-name|${referrer}`
	// So we can understand the chain better and give you all the credit you deserve!
});

Option	Default	Description	Required	Validation
referrer	-	Referrer identifier	Yes	-
dotEnvFile	".env"	Path to env file	No	letters and .
dotEnvKey	"DATABASE_URL"	Environment variable name	No	`SCREAMING_SNAKE_CASE
envPrefix	"PUBLIC_"	Prefix for public environment vars	No	-
settings	-	Database configuration settings	No	-

settings Options

Property	Type	Description	Default
logicalReplication	boolean	Enable logical replication	false

Note: The Vite plugin uses VITE_ as the default envPrefix to match Vite's convention for client-side environment variables.

Returns:

Property	Description
databaseUrl	Pooled connection string (default connection)
databaseUrlDirect	Direct connection string
claimUrl	Claim link
claimExpiresAt	Expiration date

Environment Variables Written

When you run get-db, the following environment variables are written to your .env file:

Variable	Description
DATABASE_URL	The pooler connection string (default connection)
DATABASE_URL_DIRECT	The direct connection string
{envPrefix}POSTGRES_CLAIM_URL	Claim URL (valid for 72 hours) to take ownership of the DB

Note: The pooler connection is now the default for DATABASE_URL (as of the latest version). The pooler provides connection pooling and is recommended for most use cases, especially serverless environments.

Types

// Params for instantPostgres
interface InstantPostgresParams {
	referrer: string; // Required
	dotEnvFile?: string;
	dotEnvKey?: string;
	envPrefix?: string;
	seed?: { type: "sql-script"; path: string };
	settings?: {
		logicalReplication?: boolean; // Enable logical replication (default: false)
	};
}

See documentation on Neon for more.

This package was templated with create-typescript-app using the Bingo engine.