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