@polymorphism-tech/morph-spec 4.8.19 → 4.9.0

package/framework/standards/infrastructure/vercel/vercel-database.md

@@ -0,0 +1,106 @@
+# Vercel Deployment — Database Standard
+
+> **Scope:** nextjs-vercel
+> **Layer:** 1 (always-on for Vercel-deployed Next.js)
+> **Keywords:** vercel, neon, planetscale, serverless database, serverless postgres, deploy nextjs
+> **Load When:** deployment target is Vercel with Next.js stack
+
+---
+
+## Rule: Vercel Requires a Serverless Database
+
+**NEVER** use a traditional long-lived database connection pool (PostgreSQL TCP, MySQL TCP) with Vercel.
+Vercel functions are ephemeral and stateless — each invocation may spawn a fresh process.
+A persistent connection pool (e.g., EF Core + plain Npgsql TCP) will exhaust database connection limits within minutes under moderate load.
+
+**ALWAYS** use a **serverless-compatible** database when deploying to Vercel.
+
+---
+
+## Approved Serverless Databases
+
+| Provider | Type | Connection mode | Notes |
+|----------|------|-----------------|-------|
+| **Neon** | PostgreSQL (serverless) | HTTP (`@neondatabase/serverless`) or pooled TCP via PgBouncer | First choice for SQL |
+| **PlanetScale** | MySQL-compatible (serverless) | HTTP driver (`@planetscale/database`) | Good for MySQL ecosystems |
+| **Supabase** | PostgreSQL + PgBouncer | Pooled TCP (transaction mode) or REST | Full BaaS option |
+| **Turso** | SQLite (distributed) | HTTP (`@libsql/client`) | Lightweight, edge-friendly |
+
+---
+
+## Implementation: Neon (Recommended)
+
+```ts
+// lib/db.ts
+import { neon } from '@neondatabase/serverless';
+
+const sql = neon(process.env.DATABASE_URL!);
+export default sql;
+```
+
+```ts
+// Example: API Route (app/api/items/route.ts)
+import sql from '@/lib/db';
+
+export async function GET() {
+  const items = await sql`SELECT * FROM items LIMIT 50`;
+  return Response.json(items);
+}
+```
+
+### Environment variable
+```
+DATABASE_URL=postgresql://user:pass@ep-xxx.neon.tech/dbname?sslmode=require
+```
+
+---
+
+## Implementation: Supabase + PgBouncer (Transaction Mode)
+
+Use the **port 6543** connection string (PgBouncer, transaction pooling):
+
+```
+DATABASE_URL=postgresql://user:pass@db.xxx.supabase.co:6543/postgres?pgbouncer=true&connection_limit=1
+```
+
+If using an ORM (Prisma/Drizzle), set `connection_limit=1` to avoid pool saturation.
+
+---
+
+## Anti-patterns — NEVER use with Vercel
+
+```ts
+// WRONG: plain Npgsql/pg pool without serverless adapter
+import { Pool } from 'pg';
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+// → Leaks connections on every cold start
+
+// WRONG: EF Core (dotnet) TCP pool behind a Vercel-deployed Next.js API route
+// → Not applicable (EF Core is .NET), but calling a .NET API that pools
+//   connections is fine as long as the .NET side runs on a persistent server
+```
+
+---
+
+## Decision Tree: Choose Your DB Tier
+
+```
+Deploying to Vercel?
+  └── YES → Use serverless DB
+        ├── Need SQL + PostGIS/pgvector? → Neon
+        ├── Need full BaaS (auth, storage, RLS)? → Supabase
+        ├── MySQL ecosystem? → PlanetScale
+        └── Edge-only, lightweight? → Turso
+  └── NO (EasyPanel, Railway, Render, Azure Container Apps)
+        └── Any PostgreSQL with connection pool is fine
+```
+
+---
+
+## Validator Check (design phase)
+
+During `phase-design`, the standards agent must verify:
+
+- `config.deployment.target === 'vercel'` → enforce serverless DB selection
+- If `database.provider` is missing or is `postgresql-tcp`, flag as **BLOCKING** issue
+- Add to `decisions.md`: "Database must be serverless-compatible (Vercel constraint)"