diff --git a/.env.example b/.env.example
index b5d456da..a2bdd303 100644
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,17 @@
-DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres?schema=public"
-SUPABASE_URL="http://localhost:54321"
-SUPABASE_SERVICE_ROLE_KEY="sb_secret_XXXXXXXXX"
\ No newline at end of file
+# Postgres (pooled) connection string
+# Used by the application layer, and should be configured to use connection pooling (pgbouncer) in prod
+DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres"
+
+# Postgres direct connection string
+# Used by Prisma for migrations
+DIRECT_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres"
+
+# Supabase project URL
+SUPABASE_URL="http://127.0.0.1:54321"
+
+# Supabase anonymous (public) key
+SUPABASE_ANON_KEY="sb_publishable_XXX"
+
+# Supabase service role key
+# Secret key, never expose to the client
+SUPABASE_SERVICE_ROLE_KEY="sb_secret_XXX"
\ No newline at end of file
diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 87a5ebdb..d000bdd9 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -22,9 +22,6 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Generate Prisma Client
-        run: npx prisma generate
-
       - name: Lint
         run: npm run lint
 
diff --git a/docs/SUPABASE_SETUP.md b/docs/SUPABASE_SETUP.md
index f4f6baae..ea02b356 100644
--- a/docs/SUPABASE_SETUP.md
+++ b/docs/SUPABASE_SETUP.md
@@ -47,13 +47,23 @@ These credentials are also accessible again via `npx supabase status` if you nee
 
 ### 2. Configure environment variables
 
-In your `.env` copy the "Project URL" to `SUPABASE_URL`, and the "Secret" to `SUPABASE_SERVICE_ROLE_KEY`.
+Copy `.env.example` to `.env` and fill in the credentials from the output above:
 
-For `DATABASE_URL`, you may use a locally managed instance, or use the Database "URL". Append `?schema=public` to ensure Prisma uses the public schema.
+| Variable | Source |
+| --- | --- |
+| `DATABASE_URL` | Database "URL" — used by the application layer (configure connection pooling via pgbouncer in prod) |
+| `DIRECT_URL` | Database "URL" — used by Prisma for migrations (direct connection, no pooling) |
+| `SUPABASE_URL` | "Project URL" |
+| `SUPABASE_ANON_KEY` | "Publishable" key |
+| `SUPABASE_SERVICE_ROLE_KEY` | "Secret" key (**never expose to the client**) |
+
+> Locally there is no connection pooling, so `DATABASE_URL` and `DIRECT_URL` will be the same.
 
 ```env
-DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres?schema=public"
+DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres"
+DIRECT_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres"
 SUPABASE_URL="http://127.0.0.1:54321"
+SUPABASE_ANON_KEY="sb_publishable_XXXXXXXXX"
 SUPABASE_SERVICE_ROLE_KEY="sb_secret_XXXXXXXXX"
 ```
 
diff --git a/prisma.config.ts b/prisma.config.ts
index fe058b6b..7fdb1a9b 100644
--- a/prisma.config.ts
+++ b/prisma.config.ts
@@ -8,6 +8,6 @@ export default defineConfig({
         seed: "tsx prisma/seed.ts",
     },
     datasource: {
-        url: process.env.DATABASE_URL,
+        url: process.env.DIRECT_URL ?? "",
     },
 });