Supabase

This guide discusses the concepts behind using Prisma ORM and Supabase, explains the commonalities and differences between Supabase and other database providers, and leads you through the process for configuring your application to integrate with Supabase.

What is Supabase?

Supabase is a PostgreSQL hosting service and open source Firebase alternative providing all the backend features you need to build a product. Unlike Firebase, Supabase is backed by PostgreSQL which can be accessed directly using Prisma ORM.

To learn more about Supabase, you can check out their architecture here and features here

Commonalities with other database providers

Many aspects of using Prisma ORM with Supabase are just like using Prisma ORM with any other relational database. You can still:

• Model your database with the Prisma Schema Language
• Use Prisma ORM's existing postgresql database connector in your schema, along with the connection string Supabase provides you
• Use Introspection for existing projects if you already have a database schema in Supabase
• Use db push to push changes in your schema to Supabase
• Use Prisma Client in your application to talk to the database server at Supabase

Specific considerations

If you'd like to use the connection pooling feature available with Supabase, you will need to use the connection pooling connection string available via your Supabase database settings with ?pgbouncer=true appended to the end of the environment variable that Prisma Client reads when you instantiate it with a driver adapter:

# Connect to Supabase via connection pooling with Supavisor.
DATABASE_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-[aws-region].pooler.supabase.com:6543/postgres?pgbouncer=true"

Supabase provides three types of connection strings for each database:

1. Direct Database Connection string – postgresql://postgres:password@db.[your-project-ref].supabase.co:5432/postgres

2. Transaction Pooler Connection string – postgresql://postgres.[your-project-ref]:password@aws-0-[region].pooler.supabase.com:6543/postgres

3. Session Pooler Connection string – postgresql://postgres.[your-project-ref]:password@aws-0-[region].pooler.supabase.com:5432/postgres

Prisma CLI commands (for example, migrations and introspection) now read the direct, non-pooled connection string from prisma.config.ts. Configure two environment variables — the pooled connection string for Prisma Client (DATABASE_URL) and a direct connection string for the Prisma CLI (DIRECT_URL):

# Connect to Supabase via connection pooling with Supavisor.
DATABASE_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-[aws-region].pooler.supabase.com:6543/postgres?pgbouncer=true"

# Direct connection to the database used by the Prisma CLI.
DIRECT_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-[aws-region].pooler.supabase.com:5432/postgres"
# or
DIRECT_URL="postgresql://postgres:password@db.[your-project-ref].supabase.co:5432/postgres"

Point prisma.config.ts to the direct connection string:

import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: {
    url: env("DIRECT_URL"),
  },
});

At runtime, instantiate Prisma Client with a driver adapter using the pooled DATABASE_URL. This keeps the direct connection string scoped to Prisma CLI workflows while your application connections continue to flow through Supavisor.

import { PrismaClient } from "../prisma/generated/client";
import { PrismaPg } from "@prisma/adapter-pg";

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
export const prisma = new PrismaClient({ adapter });

Getting started with Supabase

If you're interested in learning more, Supabase has a great guide for connecting a database provided by Supabase to your Prisma project available here.

If you're running into issues integrating with Supabase, check out these specific troubleshooting tips or Prisma's GitHub Discussions for more help.