Manage Neon Database — SKILL.md

---
name: "Manage Neon Database"
description: "Create and manage serverless Postgres databases on Neon — projects, branches, connection strings, Prisma setup"
version: "1.0.0"
author: "skynet"
category: "infrastructure"
agents: ["claude-code", "codex", "gemini"]
tags: ["neon", "postgres", "database", "prisma"]
tools_required: ["shell"]
---

# Manage Neon Database

# Manage Neon Database

## When to use

Use this skill when you need to create a new Postgres database, manage branches for preview environments, or set up Prisma with Neon connection pooling.

## Prerequisites

- Neon CLI installed and authenticated: `neonctl --version`
- If not installed: `npm install -g neonctl && neonctl auth`
- James's Neon org: `org-patient-sunset-05785270`

## Instructions

### Step 1: Create a new Neon project

```bash
neonctl projects create --name my-project --region-id aws-us-east-1 --org-id org-patient-sunset-05785270
```

This creates a project with a default `main` branch and `neondb` database.

### Step 2: Get connection strings

```bash
# Pooled connection (for app runtime — use this as DATABASE_URL)
neonctl connection-string --project-id <project-id> --pooled

# Direct connection (for migrations — use this as DIRECT_URL)
neonctl connection-string --project-id <project-id>
```

The pooled URL has `-pooler` in the hostname. The direct URL does not.

### Step 3: Set up Prisma 7 with Neon

**`.env`:**
```
DATABASE_URL="postgresql://user:pass@ep-xxx-pooler.us-east-1.aws.neon.tech/neondb?sslmode=require"
```

**`prisma/schema.prisma`:**
```prisma
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}
```

**`prisma.config.ts`:**
```typescript
import "dotenv/config";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: {
    // Direct URL for migrations (bypasses pooler)
    url: process.env["DIRECT_URL"] || process.env["DATABASE_URL"],
  },
});
```

**`src/lib/db.ts` (app runtime with pooler):**
```typescript
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "@/generated/prisma/client";
import { Pool } from "pg";

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

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
export const prisma = globalForPrisma.prisma || new PrismaClient({ adapter });
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;
```

### Step 4: Run migrations

```bash
npx prisma migrate dev --name init
npx prisma generate
```

### Step 5: Create a branch (for preview environments)

```bash
neonctl branches create --project-id <project-id> --name preview-123 --parent main
neonctl connection-string --project-id <project-id> --branch preview-123 --pooled
```

Branches are instant copies of the parent — zero data duplication until writes diverge.

### Step 6: List and manage projects

```bash
neonctl projects list --org-id org-patient-sunset-05785270
neonctl branches list --project-id <project-id>
neonctl databases list --project-id <project-id> --branch main
```

### Common patterns

**Quick project + Prisma setup (one-liner sequence):**
```bash
neonctl projects create --name myapp --region-id aws-us-east-1 --org-id org-patient-sunset-05785270
# Copy the connection string from output
# Add to .env as DATABASE_URL (pooled) and DIRECT_URL (direct)
npx prisma migrate dev --name init
```

**Delete a branch after PR merge:**
```bash
neonctl branches delete preview-123 --project-id <project-id>
```

**Reset a branch to match main:**
```bash
neonctl branches reset preview-123 --project-id <project-id> --parent main
```

## Troubleshooting

- **Connection timeout**: Neon has cold starts (~1s). First query after idle period may be slow. This is normal.
- **"prepared statement already exists"**: Use the pooled URL with `?pgbouncer=true` to disable prepared statements (needed for some ORMs).
- **Prisma migrate fails**: Ensure `prisma.config.ts` uses the DIRECT_URL (not pooled). Pooler doesn't support DDL well.
- **SSL errors**: Always include `?sslmode=require` in connection strings.

## References

- Neon docs: https://neon.tech/docs
- Neon CLI: https://neon.tech/docs/reference/cli-install
- James's org: `org-patient-sunset-05785270`
- Neon dashboard: https://console.neon.tech