fix(OUT-3675): updated documentation

Author: arpandhakal

.env.example

@@ -16,6 +16,9 @@ POSTGRES_USER=
 POSTGRES_HOST=
 POSTGRES_PASSWORD=
 POSTGRES_DATABASE=
+# Used by prisma/schema.prisma. Wraps POSTGRES_PRISMA_URL with Prisma pool params.
+# Keep connection_limit small (~5) for Vercel serverless — see schema.prisma for why.
+POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT="$POSTGRES_PRISMA_URL&connection_limit=5&pool_timeout=20"
 
 
 # --- Vercel hosts and credentials

AGENTS.md

@@ -18,6 +18,7 @@ yarn prettier:fix     # Prettier auto-format
 ```
 
 After changing `prisma/schema.prisma`:
+
 ```bash
 npx prisma generate   # Regenerate Prisma client (also runs on postinstall)
 npx prisma db push    # Push schema changes to database
@@ -44,6 +45,7 @@ No test suite is configured.
 ### Database (Prisma + PostgreSQL)
 
 Three models in `prisma/schema.prisma`:
+
 - `CustomFieldAccess` — per-portal field-level VIEW/EDIT permissions
 - `ClientProfileUpdates` — audit log of profile changes (stores full custom fields + changed fields as JSONB)
 - `Setting` — per-portal JSON configuration
@@ -66,6 +68,7 @@ Settings and custom field access are stored as two copies in context: a read-onl
 ## Environment Setup
 
 Copy `.env.example` to `.env.local`. Required variables:
+
 - `COPILOT_API_KEY` — from the Assembly/Copilot dashboard
 - `COPILOT_ENV` — `local` for test tokens, `production` for real tokens
 - `POSTGRES_PRISMA_URL` and related DB vars — PostgreSQL connection strings

prisma/schema.prisma

@@ -7,8 +7,10 @@ generator client {
 
 datasource db {
   provider     = "postgresql"
-  // Vercel won't let us change the POSTGRES_* config so update it with a connection_limit key using a custom env var like
-  // POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT="$POSTGRES_PRISMA_URL&connection_limit=20"
+  // Vercel won't let us edit POSTGRES_* directly, so we wrap POSTGRES_PRISMA_URL with extra params via a custom env var.
+  // For Vercel serverless, keep connection_limit small — each lambda gets its own client-side pool, and large values
+  // multiplied by concurrent lambdas saturate pgBouncer (see https://pris.ly/d/connection-pool). Recommended value:
+  // POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT="$POSTGRES_PRISMA_URL&connection_limit=5&pool_timeout=20"
   url          = env("POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT")
   directUrl    = env("POSTGRES_URL_NON_POOLING")
   // Emulates relationships in Prisma client itself. Better for serverless databases like neon or planetscale