The Case of the Frozen Supabase/Prisma db push: Why Your Migrations Might Be Stuck

Frozen Prisma `db push`: Why Your Migrations Might Be Stuck

Have you ever run npx prisma db push and watched it... do nothing? It just freezes, leaving you wondering if your database is giving you the silent treatment. If you've been working with Prisma and Supabase, you've likely encountered this exact scenario.

I recently ran into this issue while trying to push a my prisma schema:

# Regenerate client
npx prisma generate

# Attempting to push the schema
npx prisma db push --force-reset

The commands just hung, never completing successfully. A simple task becoming a frustrating blocker.

My findings: Direct Connections for Migrations

After some digging, I realized:

DIRECT_URL: This is your direct, unpooled connection to the Supabase database. This is what Prisma needs for database migrations and schema pushes.
DATABASE_URL: This is your connection string that goes through Supabase's connection pooler (Supavisor). This is ideal for your application's runtime queries, as it efficiently manages connections.

When you instruct Prisma to modify your database schema (such as with db push or migrate), it requires a direct, unmediated connection to the database. The connection pooler, while great for application traffic, can sometimes interfere with these administrative operations.

The Fix: Configure `directUrl` in Your Prisma Schema

The solution is straightforward: ensure your datasource block in schema.prisma explicitly defines directUrl and points it to your unpooled Supabase connection string.

Here's how your schema.prisma should look:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL") // Essential for migrations!
}

By adding directUrl = env("DIRECT_URL"), you're telling Prisma which connection to use for schema modifications. Ensure that your DIRECT_URL environment variable is correctly set in your development environment and any deployment pipelines.

This small but configuration change ensures your Prisma migrations run smoothly, preventing those frustrating freezes so that you can get back to writing your app.

What blocker have you faced while working with ORMs?

Gerald @geraldmuvengei06