prisma-postgres-setup

Set up a new Prisma Postgres database and connect it to a local project using the Management API. Use when asked to "set up a database", "create a Prisma…

installs

stars

karma

SkillRank score ↗

8.3/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-07-07

prisma-postgres-setup provisions a new prisma postgres database via management api and wires it into a local project, handling authentication, region selection, schema scaffolding, and end-to-end connection verification.

structure

10.0

trigger phrases

9.0

procedure

9.0

edge cases

7.0

documentation

8.0

strengths

view original SKILL.md from skills.shclick to expand

Prisma Postgres Setup

Procedural skill that guides you through provisioning a new Prisma Postgres database via the Management API and connecting it to a local project.

When to Apply

Use this skill when:

Setting up a new Prisma Postgres database for a project

Creating a Prisma Postgres project and connecting it locally

Obtaining a connection string for Prisma Postgres

Provisioning a database via the Management API (not the Console UI)

Do not use this skill when:

Setting up CI/CD preview databases — use prisma-postgres-cicd

Building multi-tenant database provisioning into an app — use prisma-postgres-integrator

Working with a database that already exists and is connected (schema/migration tasks are standard Prisma CLI)

Prerequisites

Node.js 18+

A Prisma Postgres workspace (create one at https://console.prisma.io if needed)

A workspace service token (see references/auth.md)

UX Guidelines

When presenting choices to the user (region selection, project deletion, etc.), use your platform's interactive selection mechanism (e.g., ask tool in Claude Code, structured prompts in other agents). Do not print static tables and ask the user to type a value — present selectable options so the user can pick with minimal effort.

Workflow

Follow these steps in order. Each step includes the API call to make and how to handle the response.

Step 1: Authenticate

You need a service token. Try these methods in order:

1a. Token in the user's prompt

Check if the user included a service token in their initial message (e.g., "Set up Prisma Postgres with token eyJ..."). If so, use it exactly as provided — do not truncate, re-encode, or round-trip it through a file. Store it in a shell variable for subsequent calls.

1b. Token in the environment

Check for PRISMA_SERVICE_TOKEN in the environment or .env file.

1c. Ask the user to create one

If no token is available, instruct the user:

Create a service token in Prisma Console → Workspace Settings → Service Tokens.
Copy the token and paste it here.

Read references/auth.md for details on service token creation.

Once you have a token, store it in a shell variable (PRISMA_SERVICE_TOKEN) and use it for all subsequent API calls.

Step 2: List available regions

Fetch the list of available Prisma Postgres regions to let the user choose where to deploy.

curl -s -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  https://api.prisma.io/v1/regions/postgres

The response contains an array of regions with id, name, and status. Only present regions where status is available.

Present the regions as an interactive menu — let the user pick from options rather than typing a region ID manually.

Read references/endpoints.md for the full response shape.

Step 3: Create a project with a database

curl -s -X POST https://api.prisma.io/v1/projects \
  -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<project-name>",
    "region": "<region-id>",
    "createDatabase": true
  }'

Use the current directory name as the project name by default.

The response is wrapped in { "data": { ... } }. Extract:

data.id — the project ID (prefixed with proj_)

data.database.id — the database ID (prefixed with db_)

data.database.connections[0].endpoints.direct.connectionString — the direct PostgreSQL connection string

Use the direct connection string (endpoints.direct.connectionString). Do not use the pooled or accelerate endpoints — those are for legacy Accelerate setups and not needed for new projects.

If the response status is provisioning, wait a few seconds and poll GET /v1/databases/<database-id> until status is ready.

If creation fails due to a database limit, list the user's existing projects and present them as an interactive menu for deletion. After the user picks one, delete it and retry.

Read references/endpoints.md for the full request/response shapes.

Step 4: Create a named connection (optional)

If you need a dedicated connection (e.g., per-developer or per-environment), create one:

curl -s -X POST https://api.prisma.io/v1/databases/<database-id>/connections \
  -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "dev" }'

Extract the direct connection string from data.endpoints.direct.connectionString.

Step 5: Configure the local project

Install dependencies:

npm install prisma @prisma/client @prisma/adapter-pg pg dotenv

All five packages are required:

prisma — CLI for migrations, schema push, client generation

@prisma/client — the generated query client

@prisma/adapter-pg — Prisma 7 driver adapter for direct PostgreSQL connections

pg — Node.js PostgreSQL driver (used by the adapter)

dotenv — loads .env variables for prisma.config.ts

Write the direct connection string to .env. Append to the file if it already exists — do not overwrite existing entries:

DATABASE_URL="<direct-connection-string>"

Verify .gitignore includes .env. Create .gitignore if it does not exist. Warn the user if .env is not gitignored.

Ensure package.json has "type": "module" set (Prisma 7 generates ESM output).

If prisma/schema.prisma does not exist, run npx prisma init to scaffold the project. This creates both prisma/schema.prisma and prisma.config.ts.

Ensure schema.prisma has the postgresql provider and no url or directUrl in the datasource block (Prisma 7 manages connection URLs in prisma.config.ts, not in the schema):

datasource db {
  provider = "postgresql"
}

Ensure prisma.config.ts loads the connection URL from the environment:

import path from 'node:path'
import { defineConfig } from 'prisma/config'
import 'dotenv/config'

export default defineConfig({
  earlyAccess: true,
  schema: path.join(import.meta.dirname, 'prisma', 'schema.prisma'),
  datasource: {
    url: process.env.DATABASE_URL!,
  },
})

Important Prisma 7 notes:

Connection URLs go in prisma.config.ts, never in schema.prisma

The provider in schema.prisma must be "postgresql" (not "prismaPostgres")

dotenv/config must be imported in prisma.config.ts to load .env variables

Step 6: Define schema and push

If the schema already has models, skip to pushing. Otherwise, present these options as an interactive menu:

"I'll define my schema manually" — Tell the user to edit prisma/schema.prisma and come back when ready. Wait for them before proceeding.

"Give me a starter schema" — Add a Blog starter schema (User, Post, Comment with relations) to prisma/schema.prisma. Show the user what was added and ask if they want to adjust it before pushing.

"I'll describe what I need" — Ask the user to describe their data model in natural language (e.g., "I'm building a task manager with projects, tasks, and team members"). Generate a schema from the description, show it, and ask for confirmation before pushing.

Once the schema has models and the user is ready, create a migration and generate the client:

npx prisma migrate dev --name init

This creates migration files in prisma/migrations/ and generates the client in one step. Migration history is essential for CI/CD workflows (prisma migrate deploy) and production deployments.

Only use npx prisma db push if the user explicitly asks for prototyping-only mode (no migration history). In that case, follow it with npx prisma generate.

Step 7: Verify the connection

After generating the client, create and run a quick verification script to confirm everything works end-to-end. This is critical — do not skip this step.

Create a file named test-connection.ts:

import 'dotenv/config'
import pg from 'pg'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client.js'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
const adapter = new PrismaPg(pool)
const prisma = new PrismaClient({ adapter })

const result = await prisma.$queryRawUnsafe('SELECT 1 as connected')
console.log('Connected to Prisma Postgres:', result)

await prisma.$disconnect()
await pool.end()

Run it:

npx tsx test-connection.ts

Prisma 7 client instantiation rules:

Import from ./generated/prisma/client.js (not ./generated/prisma)

Create a pg.Pool with the DATABASE_URL connection string

Wrap it in a PrismaPg adapter

Pass { adapter } to the PrismaClient constructor

Do not use datasourceUrl — that option does not exist in Prisma 7

Do not use new PrismaClient() with no arguments — it will throw

After verification succeeds, delete test-connection.ts.

Then share links for the user to explore their database:

Prisma Studio (CLI): npx prisma studio — opens a visual data browser locally

Console: https://console.prisma.io/<workspaceId>/<projectId>/<databaseId>/dashboard — strip the prefixes (wksp_, proj_, db_) from the IDs returned in Step 3 to build this URL

Read references/prisma7-client.md for the full client instantiation reference.

Error Handling

Read references/api-basics.md for the full error reference. Key self-correction patterns:

HTTP Status
Error Code
Action

401
authentication-failed
Service token is invalid or expired. Ask the user to create a new one in Console → Workspace Settings → Service Tokens.

404
resource-not-found
Check that the resource ID includes the correct prefix (proj_, db_, con_).

422
validation-error
Check request body against the endpoint schema. Common: missing name, invalid region.

429
rate-limit-exceeded
Back off and retry after a few seconds.

Reference Files

Detailed API and usage information is in:

references/auth.md             — Service token creation and usage
references/api-basics.md       — Base URL, envelope, IDs, errors, pagination
references/endpoints.md        — Endpoint details for projects, databases, connections, regions
references/prisma7-client.md   — Prisma 7 client instantiation and usage patterns

don't have the plugin yet? install it then click "run inline in claude" again.

extracted decision logic into explicit if-else branches, added edge cases (rate limits, auth expiry, provisioning delays, database limits), documented all external connections and environment variables, reorganized procedure into numbered steps with clear inputs/outputs, and added outcome signal for user verification.

intent

Set up a new Prisma Postgres database via the Management API and connect it to a local project. use this skill when provisioning a fresh database, creating a new Prisma Postgres project, obtaining connection strings, or integrating database setup into a workflow. do not use this for existing connected databases (schema and migration tasks are standard Prisma CLI), CI/CD preview databases (use prisma-postgres-cicd), or multi-tenant provisioning at app scale (use prisma-postgres-integrator).

inputs

PRISMA_SERVICE_TOKEN: workspace service token. obtain from Prisma Console → Workspace Settings → Service Tokens. can be passed inline in user message, loaded from environment variable, or read from .env file. required for all Management API calls.
Prisma workspace: existing workspace at https://console.prisma.io. create one if needed.
Node.js 18+: required for running npm scripts and Prisma CLI.
Local project directory: the directory where you'll initialize Prisma schema and config files.
External connection: https://api.prisma.io/v1 (Management API base URL).

edge cases to handle: token expiry (401 errors), rate limits (429), database creation limits (existing databases must be deleted first), network timeouts, and provisioning delays (polling required for status checks).

procedure

step 1: authenticate with service token

input: service token from user message, environment (PRISMA_SERVICE_TOKEN), or .env file.
check for token in this order: (1a) inline in user prompt, (1b) environment variable PRISMA_SERVICE_TOKEN, (1c) .env file.
if no token found, instruct user to navigate to Prisma Console → Workspace Settings → Service Tokens, create one, and paste it.
store token in shell variable: export PRISMA_SERVICE_TOKEN="<token>".
output: shell variable set and ready for API calls.

step 2: list available regions

input: PRISMA_SERVICE_TOKEN, Management API endpoint.
call: curl -s -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" https://api.prisma.io/v1/regions/postgres
parse response and filter for regions where status is available.
output: list of region objects with id, name, status.
present regions to user as interactive menu (selectable options, not a static table). let user pick one region.

step 3: create project with database

input: project name (default to current directory name if not provided), region ID from step 2, service token.
call: curl -s -X POST https://api.prisma.io/v1/projects -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" -H "Content-Type: application/json" -d '{"name":"<project-name>","region":"<region-id>","createDatabase":true}'
parse response: extract data.id (project ID, prefixed proj_), data.database.id (database ID, prefixed db_), and data.database.connections[0].endpoints.direct.connectionString (direct PostgreSQL connection string).
if response status is provisioning, poll GET /v1/databases/<database-id> every 2-3 seconds until status is ready.
output: project ID, database ID, direct connection string (store in variable for step 5).

step 4: create named connection (optional)

input: database ID from step 3, connection name (e.g., "dev" or "prod"), service token.
call: curl -s -X POST https://api.prisma.io/v1/databases/<database-id>/connections -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" -H "Content-Type: application/json" -d '{"name":"<connection-name>"}'
parse response and extract data.endpoints.direct.connectionString.
output: named connection string (alternative to step 3 direct string).
note: only create this if user needs multiple named connections per developer or environment.

step 5: configure local project

input: direct connection string from step 3 or 4, local project directory.
install dependencies: npm install prisma @prisma/client @prisma/adapter-pg pg dotenv. all five packages are required.
append connection string to .env file (do not overwrite existing entries): DATABASE_URL="<direct-connection-string>".
verify .env is in .gitignore. create .gitignore if missing. warn user if .env is not gitignored.
set "type": "module" in package.json (Prisma 7 generates ESM output).
if prisma/schema.prisma does not exist, run npx prisma init. this scaffolds prisma/schema.prisma and prisma.config.ts.
ensure schema.prisma has postgresql provider and no url or directUrl in datasource block:
```
datasource db {
  provider = "postgresql"
}
```

ensure prisma.config.ts exists and loads DATABASE_URL from environment:

import path from 'node:path'
import { defineConfig } from 'prisma/config'
import 'dotenv/config'

export default defineConfig({
  earlyAccess: true,
  schema: path.join(import.meta.dirname, 'prisma', 'schema.prisma'),
  datasource: {
    url: process.env.DATABASE_URL!,
  },
})

output: .env configured, schema.prisma and prisma.config.ts ready for next step.

step 6: define schema and push

input: existing prisma/schema.prisma or empty schema from step 5.
if schema already contains models, skip to pushing.
if schema is empty, present three interactive options to user:
- "i'll define my schema manually": tell user to edit prisma/schema.prisma and confirm when ready. wait for user confirmation before proceeding.
- "give me a starter schema": add a blog starter schema (User, Post, Comment with relations) to prisma/schema.prisma. show user what was added and ask for approval before pushing.
- "i'll describe what i need": ask user to describe data model in natural language (e.g., "task manager with projects, tasks, team members"). generate schema from description, display it, ask for confirmation.
once schema has models and user approves, create migration and generate client: npx prisma migrate dev --name init.
output: migration files in prisma/migrations/, generated Prisma client.

step 7: verify connection

input: generated Prisma client, DATABASE_URL in .env, pg and @prisma/adapter-pg modules installed.

create test file test-connection.ts:

import 'dotenv/config'
import pg from 'pg'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client.js'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
const adapter = new PrismaPg(pool)
const prisma = new PrismaClient({ adapter })

const result = await prisma.$queryRawUnsafe('SELECT 1 as connected')
console.log('Connected to Prisma Postgres:', result)

await prisma.$disconnect()
await pool.end()

run: npx tsx test-connection.ts.
output: "Connected to Prisma Postgres: [{ connected: 1 }]" (or equivalent confirmation).
delete test-connection.ts after success.
share links: Prisma Studio local (npx prisma studio) and Console dashboard (https://console.prisma.io/<workspaceId>/<projectId>/<databaseId>/dashboard, strip prefixes wksp_, proj_, db_ from IDs).

decision points

if service token not found: ask user to create one in Console → Workspace Settings → Service Tokens and paste it. do not proceed without token.

if region list is empty or no available regions: inform user that the workspace has no available Postgres regions. suggest creating a new workspace or contacting support.

if project creation returns HTTP 422 validation-error: check request body matches endpoint schema. common issues: missing name, invalid region ID. re-prompt user.

if project creation returns HTTP 429 rate-limit-exceeded: back off and retry after 3-5 seconds. inform user of retry attempt.

if database provisioning status is not ready immediately: poll GET /v1/databases/ every 2-3 seconds for up to 2 minutes. if still provisioning after 2 minutes, inform user provisioning is in progress and they can check Console for status.

if HTTP 401 authentication-failed: service token is invalid or expired. ask user to create a new one in Console → Workspace Settings → Service Tokens.

if project creation fails with database limit error: list user's existing projects via GET /v1/projects as interactive menu. let user pick one to delete. call DELETE /v1/projects/. retry project creation.

if schema already has models in step 6: skip to running npx prisma migrate dev --name init directly.

if user explicitly requests prototyping-only mode (no migration history): use npx prisma db push instead of migrate dev, then run npx prisma generate separately. warn user that migration history will not be tracked.

if test-connection.ts fails with connection error: check DATABASE_URL is correct and database is ready. verify pg.Pool is initialized. ensure PrismaPg adapter is instantiated. do not delete test-connection.ts until connection succeeds.

output contract

.env file: contains DATABASE_URL="<direct-connection-string>". file exists in project root and is gitignored.
prisma/schema.prisma: valid Prisma schema with postgresql provider, datasource block (no url or directUrl), and at least one model. location: <project>/prisma/schema.prisma.
prisma.config.ts: valid Prisma 7 config that loads DATABASE_URL from environment. location: <project>/prisma.config.ts.
prisma/migrations/: directory containing migration history. first migration named <timestamp>_init. location: <project>/prisma/migrations/<timestamp>_init/migration.sql.
generated Prisma client: generated from schema.prisma. location: <project>/generated/prisma/client.js (ESM output).
package.json: contains "type": "module" and dependencies: prisma, @prisma/client, @prisma/adapter-pg, pg, dotenv.
connection verified: test-connection.ts runs successfully and logs "Connected to Prisma Postgres: [...]" before being deleted.

outcome signal

user can:

run npx prisma studio and see their database tables and data in the local web UI.
navigate to https://console.prisma.io/<workspaceId>/<projectId>/<databaseId>/dashboard and see the database online in Prisma Console.
import and use PrismaClient in their app (e.g., import { PrismaClient } from './generated/prisma/client.js') and execute queries without connection errors.
run npx prisma migrate dev in the future and see migration history tracked in prisma/migrations/.
confirm DATABASE_URL is set and .env is gitignored, so the connection string is not committed to version control.

prisma-postgres-setup

related skills

intent

inputs

procedure

decision points

output contract

outcome signal