Prisma Postgres Setup

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

```bash 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

```bash 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:

```bash 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:

```bash 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. Wri