/prisma-postgres-setup

name: prisma-postgres-setup
description: 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 Postgres project", "get a connection string", "connect my app to Prisma Postgres", or "provision a database".
license: MIT
metadata:
  author: prisma
  version: "1.1.0"

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

1. 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`

2. 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>"

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

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

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

6. Ensure `schema.prisma` has the `postgresql` provider and **no** `url` or `direc