Prisma Postgres

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
• Linking an existing local project with prisma postgres link
• 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

Quick Reference

• create-db-cli - instant databases and current CLI flags (--ttl, --copy, --quiet, --open)
• management-api - service token and OAuth API workflows
• management-api-sdk - typed SDK usage with token storage
• console-and-connections - Console operations, prisma postgres link, direct TCP connections, and serverless-driver choices

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. Link an existing local project

Use prisma postgres link when the database already exists and you want to wire a local project to it:

prisma postgres link

For CI or other non-interactive environments:

prisma postgres link --api-key "<your-api-key>" --database "db_..."

This flow updates your local .env with DATABASE_URL, then you can run prisma generate and prisma migrate dev.

4. 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)

5. 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.

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:

npx prisma studio

Linking an existing project

If the Prisma Postgres database already exists, link the local project instead of provisioning a new one:

prisma postgres link

For CI or non-interactive usage:

prisma postgres link --api-key "<your-api-key>" --database "db_..."

This command updates or creates .env with DATABASE_URL. If the project is already linked, use --force to re-link. After linking, run prisma generate, then prisma migrate dev if you need to apply the schema.

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 pg and @prisma/adapter-pg.
• For Prisma Postgres direct TCP, include sslmode=require.

Typical direct TCP format:

DATABASE_URL="postgres://identifier:key@db.prisma.io:5432/postgres?sslmode=require"

Adapter choices

• Standard Node.js apps: prefer @prisma/adapter-pg with the direct TCP URL above.
• Edge/serverless runtimes: use @prisma/adapter-ppg with @prisma/ppg only when you specifically need the Prisma Postgres serverless driver.

References

• Prisma Postgres overview
• Viewing data
• Direct connections

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

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

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

# auto-delete sooner
npx create-db@latest --ttl 2h

# copy connection string to clipboard
npx create-db@latest --copy

# print only the connection string
npx create-db@latest --quiet

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

References

• npx create-db docs

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

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

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

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