PostgreSQL in Production: Errors, Auth & Query Patterns
These are the exact errors that show up in psql or your app logs, with the fix and why it happens. Most apply whether your Postgres instance is bare-metal, Supabase, or any other managed host.
Connecting & authenticating
11 itemsFATAL: password authentication failed for user "postgres"
Postgres password authentication failed = the role has no password, an md5 hash under a scram-sha-256 rule, or a wrong password. How to tell which.
psql: FATAL: Peer authentication failed for user "postgres"
Peer auth failed for user postgres = OS user and PG role mismatch. Fix: sudo -u postgres psql, or set a password, then move pg_hba.conf to scram-sha-256.
How to Change a PostgreSQL User Password (Supabase)
Change a PostgreSQL password with ALTER ROLE or psql \password. Reset the postgres role in Supabase from the Dashboard, plus the connection gotchas.
psql command not found: install the client or fix PATH
psql command not found = PostgreSQL client not installed, or not on PATH. Install via brew/apt/choco, or add the bin directory to PATH.
Fix PostgreSQL Server Won't Start on Mac OS X (2026)
PostgreSQL server won't start on Mac? Fix 'pg_ctl: no database directory or environment variable' and Homebrew launch issues with these exact steps.
Fix ECONNREFUSED 127.0.0.1:5432 in Docker Compose (Node)
Inside a container, 127.0.0.1 is the app container itself, not Postgres. Point DATABASE_URL at the Compose service name and wait for a healthy db.
Fix Deno 'UnsupportedCertVersion' TLS Error on Supabase
UnsupportedCertVersion TLS error on Deno Deploy breaks Supabase Postgres connections. Fix it with a workaround flag and ensure encryption stays on.
Fix Postgres 5432 bind: address already in use in Docker
On Linux, Docker cannot publish host port 5432 while a native PostgreSQL or another container listens on it. Find the owner, stop it, or map 5433:5432.
Fix ECONNREFUSED 127.0.0.1:5432 in GitHub Actions
A workflow job with container: must use the services label as host; a runner job uses localhost and ports. Sequelize CLI must also read DATABASE_URL.
Fix: Sequelize authenticate() Hangs With No Success or Error
In Docker, sequelize.authenticate() can hang forever because pg defaults connectionTimeoutMillis to 0. Set a timeout to get an error instead of silence.
PostgreSQL 18 Docker: Fix Existing Volume Startup Errors
Postgres 18 changes PGDATA and the volume mount. Keep the old cluster, mount the new parent path and verify a dump/restore before switching.
Querying & schema inspection
9 itemsPostgreSQL DESCRIBE TABLE: The psql \d Equivalent
There is no DESCRIBE TABLE in PostgreSQL — run \d table_name in psql, or query information_schema.columns from any SQL client, including Supabase.
PostgreSQL SHOW TABLES / DESCRIBE TABLE (psql + Supabase)
PostgreSQL has no SHOW TABLES. Use \dt or \d table_name in psql; use information_schema.tables in Supabase, Drizzle, or any SQL client.
How to get COUNT(*) in Supabase
Get COUNT(*) in Supabase with { count: 'exact', head: true } — the total without downloading rows. Plus planned and estimated counts for big tables.
Select the First Row per Group in Supabase Postgres
Need the latest row per user or top score per team? GROUP BY can't return the whole row — here's the PostgreSQL DISTINCT ON pattern.
Supabase Enums: ALTER TYPE ADD VALUE in Migrations
Create enums with CREATE TYPE, extend with ALTER TYPE ... ADD VALUE — run it with transactions disabled in Supabase migrations to avoid "unsafe use".
Extract date (yyyy/mm/dd) from a timestamp in PostgreSQL
Extract the date part from a timestamp in PostgreSQL and get a DATE type for insertion. See why casting works and how to format for 'yyyy/mm/dd' output.
Fix Missing Headers in PostgreSQL CSV Export (2026)
PostgreSQL CSV export missing column headers? Learn why the HEADER option fixes it and how to use COPY and \COPY correctly.
Fix: TypeORM "array is not supported in postgres"
TypeORM throws DataTypeNotSupportedError on a bare @Column() array property. Add an explicit type and array: true to fix it.
Fix Supabase CHARINDEX does not exist (SQLSTATE 42883)
CHARINDEX is a SQL Server function. Use PostgreSQL strpos with the string first, then verify the profile trigger and its inserted row.
Concurrency & production errors
6 itemsFix Postgres 'Could Not Serialize Access' (40001)
"could not serialize access due to concurrent update" (SQLSTATE 40001) is not a bug — it's REPEATABLE READ or SERIALIZABLE doing its job.
How to Drop All Tables in PostgreSQL Safely (2026)
Drop every table in PostgreSQL without dropping the database: schema reset, DO-block loop, and the guards that keep you off production.
PostgreSQL INSERT IF NOT EXISTS: ON CONFLICT and NOT EXISTS
When concurrent inserts hit a unique constraint, you get 'duplicate key value violates unique constraint'. Learn how to use ON CONFLICT DO NOTHING with RETURNING to safely insert only if the row doesn't exist.
Fix Foreign Key Constraint Violation in Supabase (23503)
Error 23503 "violates foreign key constraint" means a missing parent row or a blocked delete — fix with insert order, ON DELETE CASCADE or RESTRICT.
Fix Drizzle Rollback: let the exception escape
Drizzle tx.rollback() throws. If an inner catch suppresses it, PostgreSQL can commit. Rethrow the exception and handle failure outside db.transaction().
Drizzle "table name specified more than once" in nested with
Drizzle 0.x joins relation keys into nested aliases; past 63 bytes PostgreSQL cuts two to one name. Split the query or use Relational Queries v2.
Prisma & Drizzle on Postgres
31 itemsHow to Get Enums in Prisma Client: Import, Query
Can't find your Prisma schema enums in the generated client? Learn to import, query, and validate enum values in TypeScript with @prisma/client.
Prisma: Can't reach database server at database:5432 on M1
Prisma P1001 on an M1 Docker setup needs a hostname, shared-network and readiness check. A longer timeout cannot repair a missing route.
Prisma: Environment variable not found: DATABASE_URL
Prisma throws 'Environment variable not found: DATABASE_URL' even with a .env file. Regenerate the client, and load .env.local explicitly.
prepared statement s0 already exists: Fix for Prisma +
Prisma throws 'prepared statement s0 already exists' on Supabase's pooled PostgreSQL. Fix it with directUrl and pgbouncer=true in your datasource.
Fix Prisma Query Engine Library Not Found
Prisma throws 'Query engine library for current platform debian-openssl-1.1.x could not be found'. Fix it with binaryTargets in schema.prisma.
Prisma Can't Connect to PostgreSQL: Fix invalid port
When Prisma throws "invalid port number" despite a correct port, the real culprit is unescaped special characters in your DATABASE_URL. Learn to percent-encode passwords and verify the connection.
Prisma Migrate Dev Hangs? Fix the Supabase Pooler Stall
prisma migrate dev stalls after the Datasource line when its URL uses Supabase's transaction pooler on port 6543. Give the Prisma CLI port 5432.
Prisma Migrate P3014: permission denied to create database
Fix the Prisma Migrate P3014 error on Heroku Postgres by using `prisma db push`, setting up a shadow database, or granting CREATEDB.
Fix: Can't Migrate Schema Using Prisma With Supabase
In 2022 prisma migrate dev failed with "FATAL: bouncer config error" on Supabase's pooled port 6543. Give the Prisma CLI port 5432 and it migrates.
Prisma deleteMany: Foreign key constraint failed (P2003)
P2003 on deleteMany means child rows still reference the parent. Delete the children first, or set onDelete: Cascade and run a migration.
Prisma $queryRaw Fails With Variables Inside Single Quotes
A ${value} inside a quoted SQL literal is not a parameter, so $queryRaw errors or returns wrong rows. Move the value out of the quotes.
Fix: drizzle-kit push — statement does not return data
This TypeError happens when drizzle-kit's SQLite introspection calls .get()/.all() against a driver method built for statements with no result rows.
Fix npx prisma db push Hanging on Supabase (Port 6543)
npx prisma db push stalls after the Datasource line when the URL uses Supabase's transaction pooler on 6543. Give the Prisma CLI the 5432 session URL.
Prisma $queryRaw TS2345: 'string' not assignable to Sql
TypeScript error TS2345 in NestJS: brackets turned the SQL into a plain string. Call it as a tagged template or Prisma.sql, or the Unsafe variant with $1.
Prisma nested connect: syntax error at or near "ON"
Prisma links many-to-many rows with INSERT ... ON CONFLICT DO NOTHING, which PostgreSQL only parses from 9.5. Move the data to a supported major.
Fix drizzle-kit migrate Hanging After Using 'pg' Driver
drizzle-kit migrate 0.31.x stalls after "Using pg driver" with no error. Run the drizzle-orm migrator yourself, or pin the 0.30 release the reporters fell back to.
Drizzle: Offset is outside the bounds of the DataView
Drizzle 0.x with queries return a PostGIS geometry as GeoJSON and parseEWKB crashes on it. Use a join, a custom type, or Relational Queries v2.
Keystone 6 Foreign Key NOT NULL on a Relationship Field
Keystone relationship fields have no isRequired or isNullable option. Make the column NOT NULL with db.extendPrismaSchema, then add validate hooks.
Drizzle TableLikeHasEmptySelection error in generic helpers
Since drizzle-orm 0.39.0, a generic subquery or table passed to .from() fails with TS2345. Widen the argument at the call site until the pending rc.5 fix ships.
Fix Prisma 42P01: table exists but raw query cannot find it
PostgreSQL folds unquoted table names to lowercase. Match the physical name with double quotes in Prisma raw SQL, then check its schema.
Fix Prisma v7 paths[1] must be of type string error
Prisma throws ERR_INVALID_ARG_TYPE "paths[1]" after upgrading to v7. The cause is a prisma/@prisma client version mismatch, fixed by matching versions.
Fix Prisma "Could not figure out an ID in create" panic
Prisma panics when INSERT ... RETURNING returns no row. Upgrade the replay proxy (keploy) or make the BEFORE INSERT trigger RETURN NEW.
Drizzle db.query drops pgSchema: relation does not exist
relation "user" does not exist from db.query on drizzle-orm 0.39.1-0.40.1: a pgSchema table keyed by its own name loses its schema. Upgrade to 0.41+.
Prisma "Ambiguous relation detected": name both relations
Two Prisma relations join the same two models with no name. Give each pair its own @relation("Name") on both sides, then re-run prisma validate.
Drizzle: Cannot destructure property 'resourceArn' fix
drizzle-orm 0.35.0-0.40.1 rejects the RDSDataClient drizzle-kit bundles, or your config lacks connection. Upgrade drizzle-orm or wrap the keys.
Fix Prisma 'Unique constraint failed on the fields: (id)'
Rows inserted with explicit ids left the PostgreSQL sequence behind autoincrement(). Move it past max(id) with setval and create() works again.
Drizzle: Object literal may only specify known properties
With strict off, drizzle-orm 0.32.0 to 0.42.x drops nullable and default columns from insert and set types. Upgrade to 0.43.0 or enable strictNullChecks.
Prisma Nested Create Returns Undefined: Include the Relation
Prisma writes nested records but omits relations from the returned object. Add include or nested select, then verify the children using the created id.
drizzle-kit migrate: relation "users" already exists
drizzle-kit push built the tables but wrote no migration log, so migrate replays 0000. Record the migrations already applied, then migrate again.
Drizzle D1: migrations do not match any local migration
On the Drizzle rc.4 pair, d1-http reads the migration log as objects, not arrays, so every row looks unknown. Upgrade drizzle-kit and drizzle-orm to rc.5.
drizzle-seed reset() fails on drizzle-orm beta/rc: fix
drizzle-seed 0.3.1 imports names that drizzle-orm 1.0 moved or renamed. Install the seed build from the same line: drizzle-seed@rc or @beta.
Other hubs
Next.js + Supabase: The Complete Resource Hub
Everything you need to build production-ready full-stack apps with Next.js 15 and Supabase — authentication, RLS, deployments, performance, and architecture decisions.
Next.js Errors: Build, Dev Server, Rendering & Routing Fixes
Fixes for the Next.js errors developers paste into a search bar: ChunkLoadError, prerender and "use cache" build failures, hydration warnings, the useSearchParams Suspense error, port and next/image configuration.
Supabase Debugging & Troubleshooting Hub
Field-tested fixes for the Supabase errors that actually waste your time: RLS silent failures, session persistence, slow queries, realtime gotchas, and auth redirects.
n8n Automation: Real Workflows from Real Projects
Practical n8n automation guides built from actual client work — CRM lead capture, client reporting, Zapier migration, silent failure debugging, and self-hosted AI with Ollama.
TypeScript Type Errors: Fixes for Next.js Developers
The TypeScript compiler errors (TS2322, TS2305, TS7016, TS2564 and friends) you actually hit building Next.js apps, with the fix and the type-system reasoning behind it.