supabase-postgres-best-practices/skills/supabase/references/db-conn-pooling.md

title, impact, impactDescription, tags

title	impact	impactDescription	tags
Use Correct Connection Pooling Mode	CRITICAL	Prevents connection exhaustion and enables 10-100x scalability	connection-pooling, supavisor, transaction-mode, session-mode

Use Correct Connection Pooling Mode

Supabase provides Supavisor for connection pooling. Choose the right mode based on your application type.

Transaction Mode (Port 6543)

Best for: Serverless functions, edge computing, stateless APIs.

## Transaction mode connection string
postgres://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

Limitations:

• No prepared statements
• No SET commands
• No LISTEN/NOTIFY
• No temp tables

// Prisma - disable prepared statements
const prisma = new PrismaClient({
  datasources: {
    db: {
      url: process.env.DATABASE_URL + "?pgbouncer=true",
    },
  },
});

Session Mode (Port 5432)

Best for: Long-running servers, apps needing prepared statements.

## Session mode (via pooler for IPv4)
postgres://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres

Direct Connection (Port 5432)

Best for: Migrations, admin tasks, persistent servers.

## Direct connection (IPv6 only unless IPv4 add-on enabled)
postgres://postgres.[ref]:[password]@db.[ref].supabase.co:5432/postgres

Common Mistakes

Incorrect:

// Serverless with session mode - exhausts connections
const pool = new Pool({
  connectionString: "...pooler.supabase.com:5432/postgres",
  max: 20, // Too many connections per instance!
});

Correct:

// Serverless with transaction mode
const pool = new Pool({
  connectionString: "...pooler.supabase.com:6543/postgres",
  max: 1, // Single connection per serverless instance
});

Incorrect:

## Transaction mode with prepared statements
DATABASE_URL="...pooler.supabase.com:6543/postgres"
## Error: prepared statement already exists

Correct:

## Add pgbouncer=true to disable prepared statements
DATABASE_URL="...pooler.supabase.com:6543/postgres?pgbouncer=true"

Connection Limits by Compute Size

Compute	Direct Connections	Pooler Clients
Nano	60	200
Small	90	400
Medium	120	600
Large	160	800

Related

• Docs