Adding Supabase PostgreSQL to Rackit (Prisma + Next.js App Router)

Supabase with Prisma when I tried this out in the rackit codebase.

  • Next.js 16 (App Router)
  • Prisma ORM
  • Supabase PostgreSQL
  • NextAuth.js with Prisma adapter

Prerequisites

  • Node.js 20+
  • A Supabase account and project
  • Existing Rackit repo cloned locally

Step 1 - Install dependencies

Rackit already uses Prisma + Postgres adapter. If you are adding Supabase support to a fresh branch, ensure these are installed:

1
npm install prisma @prisma/client @prisma/adapter-pg pg

If you are using Rackit as-is, this is already done.

Step 2 - Create a Supabase project and get connection strings

In Supabase:

  1. Create a new project.
  2. Go to Project Settings -> Database -> Connection string.
  3. Copy both URLs:
    • Transaction pooler (port 6543)
    • Direct connection (port 5432)

Rackit uses:

  • DATABASE_URL for application runtime (pooled)
  • DIRECT_URL for Prisma CLI (migrations)

Step 3 - Configure environment variables

Copy .env.example to .env.local and fill in values:

1
cp .env.example .env.local

Required values:

1
2
3
4
DATABASE_URL=postgresql://...:6543/postgres?pgbouncer=true
DIRECT_URL=postgresql://...:5432/postgres
NEXTAUTH_SECRET=...
NEXTAUTH_URL=http://localhost:3000

Generate NEXTAUTH_SECRET with:

1
openssl rand -base64 32

Step 4 - Confirm Prisma runtime wiring

Rackit is set up to use pooled Postgres at runtime via @prisma/adapter-pg:

  • src/lib/prisma.ts reads DATABASE_URL
  • prisma.config.ts reads DIRECT_URL for CLI operations

This split is important:

  • pooled URL for app requests
  • direct URL for migrations and schema introspection

Step 5 - Define or update the Prisma schema

Edit prisma/schema.prisma to add or change models.

Rackit datasource uses PostgreSQL:

1
2
3
datasource db {
  provider = "postgresql"
}

After schema changes, create a migration.

Step 6 - Run migrations (local development)

This is the main workflow for schema updates.

Create and apply a new migration

1
npx prisma migrate dev --name <describe_change>

Example:

1
npx prisma migrate dev --name add_team_alias

What this does:

  1. Creates SQL migration files in prisma/migrations/...
  2. Applies the migration to your Supabase database using DIRECT_URL
  3. Updates Prisma Client

Regenerate Prisma Client manually (optional)

1
npx prisma generate

Inspect data quickly

1
npx prisma studio

Step 7 - Migration workflow for deployment

Rackit’s build script already applies committed migrations:

1
"build": "prisma generate && prisma migrate deploy && next build"

That means production/preview environments run:

1
npx prisma migrate deploy

migrate deploy only applies existing migration files. It does not create new ones.

So the expected team workflow is:

  1. Change prisma/schema.prisma
  2. Run npx prisma migrate dev --name ... locally
  3. Commit both schema and generated files in prisma/migrations/
  4. Deploy - Vercel runs prisma migrate deploy

Step 8 - Verify setup

Run:

1
2
npm install
npm run dev

If setup is correct, app boots and Prisma can read/write data in Supabase.

Files involved in Supabase setup

File Purpose
.env.example Documents required Supabase and auth env vars
.env.local Local secrets and connection strings
prisma/schema.prisma Data model source of truth
prisma/migrations/* Versioned SQL migrations committed to git
prisma.config.ts Prisma CLI datasource config (DIRECT_URL)
src/lib/prisma.ts Runtime Prisma client (DATABASE_URL pooled)
package.json Build pipeline runs prisma migrate deploy

Common migration pitfalls

Problem Cause Fix
Migration works locally but fails in deploy Migration files were not committed Commit prisma/migrations/* and redeploy
prisma migrate dev cannot connect Wrong or missing DIRECT_URL Use Supabase direct connection URL on port 5432
Runtime query errors/timeouts App using direct/non-pooled URL under load Ensure DATABASE_URL is transaction pooler URL (6543)
Prisma client out of date Generated client not refreshed Run npx prisma generate

One-command checklist

1
2
3
4
cp .env.example .env.local
npm install
npx prisma migrate dev --name init
npm run dev