create-db 1.1.2-pr44-DC-4828-json-flag-17109503084.0 → 1.1.2

package/README.md

@@ -1,106 +1,239 @@
-## **What is `create-db`?**
+# create-db
 
-`create-db` is an open-source CLI tool that provisions [**temporary Prisma Postgres databases**](https://www.prisma.io/postgres?utm_source=create_db_npm_docs) with a single command.
+`create-db` is an open-source CLI tool and library that provisions [**temporary Prisma Postgres databases**](https://www.prisma.io/postgres?utm_source=create_db_npm_docs) 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 CLI output.
+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**
+## Installation and Usage
 
-There is no need to install the tool globally. Simply run:
+No installation required. Simply run:
 
 ```bash
 npx create-db@latest
 ```
 
-You can also use the following aliases:
+You can also use these aliases:
 
 ```bash
 npx create-pg@latest
 npx create-postgres@latest
 ```
 
-## **Examples**
+## CLI Usage
 
-```bash
-npx create-db                    # Creates a database in the default region
-npx create-db --region eu-west-1 # Creates a database in a specific region
-npx create-db --i                # Interactive region selection
+### Commands
 
+```bash
+npx create-db [create]   # Create a new database (default command)
+npx create-db regions    # List available regions
 ```
 
-## **Available options**
+### 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
+
+```bash
+# 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
 
-You can run `npx create-db --help` or `npx create-db -h` to see all the available CLI options:
+# 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
 ```
-npx create-db [options]
 
-Options:
-  --region <region>, -r <region>  Specify a region
-                                  Available regions:
-                                  ap-southeast-1, ap-northeast-1,
-                                  eu-central-1, eu-west-3,
-                                  us-east-1, us-west-1
+### JSON Output
+
+When using `--json`, the output includes:
+
+```json
+{
+  "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_..."
+}
+```
 
-  --interactive, -i               Run in interactive mode
+### Environment File Output
 
-  --help, -h                      Show this help message
+When using `--env`, the following variables are appended to the specified file:
 
+```env
+DATABASE_URL="postgresql://user:pass@host:5432/postgres?sslmode=require"
+CLAIM_URL="https://create-db.prisma.io/claim?projectID=..."
 ```
 
-## **CLI output example**
+## Programmatic API
 
+You can also use `create-db` as a library in your Node.js applications:
+
+```bash
+npm install create-db
+# or
+bun add create-db
 ```
-┌  🚀 Creating a Prisma Postgres database
-│
-│  Provisioning a temporary database in us-east-1...
-│
-│  It will be automatically deleted in 24 hours, but you can claim it.
-│
-◇  Database created successfully!
-│
-●  Connect to your database →
-│
-│    Prisma connection string:
-│    prisma+postgres://accelerate.prisma-data.net/?api_key=...
-│
-│    Standard connection string:
-│    postgresql://<username>:<password>@db.prisma.io:5432/postgres
-│
-◆  Claim your database →
-│
-│    Want to keep your database? Claim for free:
-│    https://create-db.prisma.io?projectID=proj_...
-└
 
+### `create(options?)`
+
+Create a new Prisma Postgres database programmatically.
+
+```typescript
+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}`);
+}
 ```
 
-## **Claiming a database**
+#### Options
 
-When you create a database using `create-db`, it is temporary and will be deleted automatically after **24 hours**.
+| 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) |
 
-The CLI output includes a **claim URL** that allows you to keep the database permanently for free.
+### `regions()`
 
-**What claiming does:**
+List available Prisma Postgres regions.
+
+```typescript
+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
+
+```typescript
+import { create, isDatabaseSuccess, isDatabaseError } from "create-db";
 
-- 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.
+const result = await create();
 
-Example:
+if (isDatabaseSuccess(result)) {
+  // result is DatabaseResult
+  console.log(result.connectionString);
+}
 
+if (isDatabaseError(result)) {
+  // result is DatabaseError
+  console.error(result.message);
+}
 ```
-◆  Claim your database →
-│
-│    Want to keep your database? Claim for free:
-|
-│    https://create-db.prisma.io?projectID=proj_...
-│
-│    Your database will be deleted on 7/24/2025, 2:25:41 AM if not claimed.
+
+### Types
+
+```typescript
+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
 ```
 
-## **Next steps**
+### Region Validation with Zod
+
+```typescript
+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 section in the official [Prisma Postgres documentation](https://www.prisma.io/docs/postgres/introduction/npx-create-db).
+- Refer to the [Prisma Postgres documentation](https://www.prisma.io/docs/postgres/introduction/npx-create-db) for more details.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { n as createDbCli } from "./src-CIUkHOCN.mjs";
+
+//#region src/cli.ts
+createDbCli().run();
+
+//#endregion
+export {  };

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import * as trpc_cli0 from "trpc-cli";
+import z$1 from "zod";
+
+//#region src/types.d.ts
+declare const RegionSchema: z$1.ZodEnum<{
+  "ap-southeast-1": "ap-southeast-1";
+  "ap-northeast-1": "ap-northeast-1";
+  "eu-central-1": "eu-central-1";
+  "eu-west-3": "eu-west-3";
+  "us-east-1": "us-east-1";
+  "us-west-1": "us-west-1";
+}>;
+type RegionId = z$1.infer<typeof RegionSchema>;
+interface Region {
+  id: string;
+  name?: string;
+  status: string;
+}
+interface DatabaseResult {
+  success: true;
+  connectionString: string | null;
+  claimUrl: string;
+  deletionDate: string;
+  region: string;
+  name: string;
+  projectId: string;
+  userAgent?: string;
+}
+interface DatabaseError {
+  success: false;
+  error: string;
+  message: string;
+  raw?: string;
+  details?: unknown;
+  status?: number;
+}
+type CreateDatabaseResult = DatabaseResult | DatabaseError;
+declare function isDatabaseError(result: CreateDatabaseResult): result is DatabaseError;
+declare function isDatabaseSuccess(result: CreateDatabaseResult): result is DatabaseResult;
+interface ProgrammaticCreateOptions {
+  region?: RegionId;
+  userAgent?: string;
+}
+//#endregion
+//#region src/index.d.ts
+declare function createDbCli(): trpc_cli0.TrpcCli;
+/**
+ * Create a new Prisma Postgres database programmatically.
+ *
+ * @param options - Options for creating the database
+ * @param options.region - The AWS region for the database (optional)
+ * @param options.userAgent - Custom user agent string (optional)
+ * @returns A promise that resolves to either a {@link DatabaseResult} or {@link DatabaseError}
+ *
+ * @example
+ * ```typescript
+ * 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}`);
+ * } else {
+ *   console.error(`Error: ${result.message}`);
+ * }
+ * ```
+ */
+declare function create(options?: ProgrammaticCreateOptions): Promise<CreateDatabaseResult>;
+/**
+ * List available Prisma Postgres regions programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { regions } from "create-db";
+ *
+ * const availableRegions = await regions();
+ * console.log(availableRegions);
+ * ```
+ */
+declare function regions(): Promise<Region[]>;
+//#endregion
+export { type CreateDatabaseResult, type DatabaseError, type DatabaseResult, type ProgrammaticCreateOptions, type Region, type RegionId, RegionSchema, create, createDbCli, isDatabaseError, isDatabaseSuccess, regions };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { a as isDatabaseError, i as RegionSchema, n as createDbCli, o as isDatabaseSuccess, r as regions, t as create } from "./src-CIUkHOCN.mjs";
+
+export { RegionSchema, create, createDbCli, isDatabaseError, isDatabaseSuccess, regions };