Prisma Postgres

Guidance for creating, managing, and integrating Prisma Postgres across interactive and programmatic workflows.

When to Apply

Reference this skill when:

• Setting up Prisma Postgres from Prisma Console
• Provisioning instant temporary databases with create-db
• Managing Prisma Postgres resources via Management API
• Using @prisma/management-api-sdk in TypeScript/JavaScript
• Handling claim URLs, connection strings, regions, and auth flows

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	CLI Provisioning	CRITICAL	create-db-cli
2	Management API	CRITICAL	management-api
3	Management API SDK	HIGH	management-api-sdk
4	Console and Connections	HIGH	console-and-connections

Quick Reference

• create-db-cli - instant databases and CLI options
• management-api - service token and OAuth API workflows
• management-api-sdk - typed SDK usage with token storage
• console-and-connections - Console operations and connection setup

Core Workflows

1. Console-first workflow

Use Prisma Console for manual setup and operations:

• Open https://console.prisma.io
• Create/select workspace and project
• Use Studio in the project sidebar to view/edit data
• Retrieve direct connection details from the project UI

2. Quick provisioning with create-db

Use create-db when you need a database immediately:

npx create-db@latest

Aliases:

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

For app integrations, you can also use the programmatic API (create() / regions()) from the create-db npm package.

Temporary databases auto-delete after ~24 hours unless claimed.

3. Programmatic provisioning with Management API

Use API endpoints on:

https://api.prisma.io/v1

Explore the schema and endpoints using:

• OpenAPI docs: https://api.prisma.io/v1/doc
• Swagger Editor: https://api.prisma.io/v1/swagger-editor

Auth options:

• Service token (workspace server-to-server)
• OAuth 2.0 (act on behalf of users)

4. Type-safe integration with Management API SDK

Install and use:

npm install @prisma/management-api-sdk

Use createManagementApiClient for existing tokens, or createManagementApiSdk for OAuth + token refresh.

Rule Files

Detailed guidance lives in:

references/console-and-connections.md
references/create-db-cli.md
references/management-api.md
references/management-api-sdk.md

How to Use

Start with references/create-db-cli.md for fast setup, then switch to references/management-api.md or references/management-api-sdk.md when you need programmatic provisioning.

---

Referenced Files

The following files are referenced in this skill and included for context.

references/console-and-connections.md

# console-and-connections

Use Prisma Console workflows for project visibility, data inspection, and connection setup.

## Priority

HIGH

## Why It Matters

Many Prisma Postgres tasks are quickest in the Console: viewing Studio data, checking metrics, and retrieving connection details. This avoids unnecessary API or CLI work for simple operational tasks.

## Console workflow

1. Open `https://console.prisma.io`.
2. Select workspace and project.
3. Use dashboard metrics for usage and billing visibility.
4. Open the **Studio** tab in the sidebar to inspect and edit data.

## Local Studio

You can also inspect data locally:

```bash
npx prisma studio

Connection setup

For direct PostgreSQL tools and drivers:

• Generate/copy direct connection credentials from the project connection UI.
• Use the resulting PostgreSQL URL as DATABASE_URL.
• For Prisma Postgres direct TCP, include sslmode=require.

References

• Prisma Postgres overview
• Viewing data
• Direct connections

### references/management-api.md

```markdown
# management-api

Use Prisma Management API for programmatic provisioning and workspace/project/database management.

## Priority

CRITICAL

## Why It Matters

When you need backend automation, multi-tenant onboarding flows, or controlled resource provisioning, the Management API is the source of truth and is more reliable than interactive workflows.

## Base URL

```text
https://api.prisma.io/v1

API exploration

• OpenAPI docs: https://api.prisma.io/v1/doc
• Swagger Editor: https://api.prisma.io/v1/swagger-editor

Authentication methods

• Service token: best for server-to-server operations in your own workspace
• OAuth 2.0: best for acting on behalf of users across workspaces

Service token flow

1. Create token in Prisma Console workspace settings.
2. Send token as Bearer auth:

Authorization: Bearer $TOKEN

OAuth flow summary

1. Redirect user to https://auth.prisma.io/authorize with client_id, redirect_uri, response_type=code, and scopes.
2. Receive code on callback.
3. Exchange code at https://auth.prisma.io/token.
4. Use returned access token in Management API requests.

Common endpoints

• GET /workspaces
• GET /projects
• POST /projects
• Database management endpoints under project/database paths

Notes

• Management API responses may include direct connection credentials for databases.
• Build PostgreSQL DATABASE_URL from direct connection values when needed.

References

• Management API docs
• OpenAPI docs
• Swagger Editor

### references/create-db-cli.md

```markdown
# create-db-cli

Use `create-db` for instant Prisma Postgres provisioning from the terminal.

## Priority

CRITICAL

## Why It Matters

`create-db` is the fastest way to get a working Prisma Postgres instance for development, demos, and CI previews. It can also emit machine-readable output and write env variables directly.

## Commands

```bash
npx create-db@latest
npx create-db@latest create [options]
npx create-db@latest regions

Aliases:

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

Command discovery (--help)

Always use --help first when integrating CLI commands:

npx create-db@latest --help
npx create-db@latest create --help
npx create-db@latest regions --help

Top-level commands currently exposed:

• create (default) to provision a database
• regions to list available regions

create options

Flag	Shorthand	Description
--region [string]	-r	Region choice: ap-southeast-1, ap-northeast-1, eu-central-1, eu-west-3, us-east-1, us-west-1
--interactive [boolean]	-i	Open region selector
--json [boolean]	-j	Output machine-readable JSON
--env [string]	-e	Write DATABASE_URL and CLAIM_URL into a target .env

Lifecycle and claim flow

• Databases are temporary by default.
• Unclaimed databases are auto-deleted after ~24 hours.
• Claim the database using the URL shown in command output to keep it permanently.

Programmatic usage (library API)

You can also use create-db programmatically in Node.js/Bun instead of shelling out to the CLI.

Install:

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

Create a database:

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

const result = await create({
  region: "us-east-1",
  userAgent: "my-app/1.0.0",
});

if (isDatabaseSuccess(result)) {
  console.log(result.connectionString);
  console.log(result.claimUrl);
  console.log(result.deletionDate);
}

if (isDatabaseError(result)) {
  console.error(result.error, result.message);
}

List regions programmatically:

import { regions } from "create-db";

const available = await regions();
console.log(available);

Programmatic create() defaults to us-east-1 if no region is passed.

Common patterns

# quick database
npx create-db@latest

# region-specific database
npx create-db@latest --region eu-central-1

# interactive region selection
npx create-db@latest --interactive

# write env vars for app bootstrap
npx create-db@latest --env .env

# CI-friendly output
npx create-db@latest --json

References

• npx create-db docs

### references/management-api-sdk.md

```markdown
# management-api-sdk

Use `@prisma/management-api-sdk` for typed API integration with optional OAuth and token refresh.

## Priority

HIGH

## Why It Matters

The SDK provides typed endpoint methods and removes boilerplate around auth and refresh handling, which reduces errors in production provisioning flows.

## Install

```bash
npm install @prisma/management-api-sdk

Simple client (existing token)

import { createManagementApiClient } from '@prisma/management-api-sdk'

const client = createManagementApiClient({ token: process.env.PRISMA_SERVICE_TOKEN! })
const { data: workspaces } = await client.GET('/v1/workspaces')

Full SDK (OAuth + refresh)

import { createManagementApiSdk, type TokenStorage } from '@prisma/management-api-sdk'

const tokenStorage: TokenStorage = {
  async getTokens() { return null },
  async setTokens(tokens) {},
  async clearTokens() {},
}

const api = createManagementApiSdk({
  clientId: process.env.PRISMA_CLIENT_ID!,
  redirectUri: 'https://your-app.com/auth/callback',
  tokenStorage,
})

OAuth SDK flow

1. Call getLoginUrl() and persist state + verifier.
2. Redirect user to login URL.
3. Handle callback with handleCallback().
4. Use api.client for typed endpoint calls.
5. Call logout() when needed.

References

• Management API SDK docs