Supabase DATABASE_URL Doctor
Most “can’t connect” errors are not the database — they are the connection string. A @ in the password, postgres instead of postgres.<project-ref> on the pooler, 6543 without pgbouncer=true, migrations sent through transaction mode. Paste yours and pick your client.
Runs entirely in your browser — nothing you paste is sent anywhere, and the password is masked in every result. Still cautious? Replace the password with any string containing the same special characters: the diagnosis only needs its shape.
What gets checked
Unencoded characters in the password or user
@ / ? # [ ] spaces and stray % break URL parsing (RFC 3986); the fix is percent-encoding, not a new password. source
Template placeholders left in
[YOUR-PASSWORD], [PROJECT-REF] or [POOLER-HOST] copied verbatim from the docs. source
Pooler username format
the shared pooler needs postgres.<project-ref>; direct connections use plain postgres. source
5432 vs 6543
session mode vs transaction mode on the pooler, direct vs dedicated pooler on db.<ref>.supabase.co. source
db.<ref>.supabase.co is IPv6
the direct connection (5432) and the dedicated pooler (6543) alike, unless you bought the IPv4 add-on — Vercel, GitHub Actions and Render are IPv4-only. source
Prepared statements in transaction mode
pgbouncer=true for Prisma, prepare: false for postgres.js, named queries for pg. source
Migrations through the transaction pooler
Prisma Migrate and pg_dump need a direct or session connection (directUrl / prisma.config.ts). source
sslmode
invalid values, SSL disabled on Supabase, no-verify, and how node-postgres (and Prisma 7 through @prisma/adapter-pg) reads sslmode=require. source
Generic Postgres checks
missing database name or port, localhost in a deployed config, Supabase API URL pasted instead of a database URL. source
Every rule is checked against the vendor’s own documentation (Supabase, Prisma, node-postgres, the PostgreSQL manual, RFC 3986); each finding links the page it comes from.
The string is right but it still will not connect?
Read why serverless functions exhaust Postgres connections and how the pooler modes differ, or the walkthrough of Prisma’s misleading “invalid port number” error.
Supabase connection pooling on serverlessStep-by-step fixes for these errors
This tool runs on dev-error-explainers, an open-source, zero-dependency library — view the source on GitHub.