HTTP Drivers at the Edge

Move one database call into middleware.ts, deploy, and the same code that ran locally now fails at import time. Next.js has two runtimes, and the difference is capability, not speed:

Middleware always runs on the edge; App Router routes opt in with export const runtime = 'edge'. In that runtime, loading a TCP-based driver produces:

⨯ A Node.js API is used (net.Socket) which is not supported in the Edge Runtime.

Prisma's classic client fails for a related but distinct reason: its query engine is a long-lived process speaking the wire protocol over a socket, and there is no socket and no process to spawn. The failure happens when the module loads — before any query you wrote runs — which is why the stack trace points at an import rather than at your logic.

The second trap is geographic. Locally your URL says localhost:5432, and it resolves to the Postgres running on your laptop. An edge function executes on someone else's machine in another city or country: localhost there is that machine, so you get ECONNREFUSED — or, if you pointed at a real host, a private VPC address the edge network cannot route to at all. The error is not "database down"; it is "this runtime was never on your network."

So the design question is not can I query here but what transport survives here. Two properties define the answer: the driver must speak HTTP (anything fetch can do, the edge can do), and connection pooling must live somewhere that outlives the invocation. Before that, one callback to Applying Schema Migrations: migrate deploy belongs in a plain Node CI job — you cannot apply DDL from a runtime that has no socket to open. The transport options for queries themselves follow.

Knowing where each file executes saves you a debugging session:

The standard fix is a division of labor: middleware handles the request — redirects, cookie reads, headers — and calls a Route Handler or Server Component for anything that needs the database. Recent Next.js lines are adding an experimental Node runtime for middleware as an opt-in; until it is stable, assume edge there. And remember the fourth row: a client component cannot reach your database through any runtime trick, because no server code runs in it.

The errors separate cleanly once you know the layers: an unsupported-API error names the missing module (net, fs) and appears at import time, a configuration error names the variable, and a network error names the host. Reading the first line of the message rather than the tail of the stack is usually enough to place the failure.

An HTTP driver replaces the persistent socket with one HTTPS request per query — or per batch of queries. Nothing is held open, nothing survives the invocation, and it works anywhere fetch exists:

import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);   // the https endpoint is derived from the URL

export async function recentOrders(orgId: string) {
  return sql`SELECT id, total, status FROM "Order"
             WHERE org_id = ${orgId} ORDER BY created_at DESC LIMIT 10`;
}

The tagged template is not cosmetic: interpolated values are bound as parameters, so ' OR 1=1-- arrives as data, never as SQL. This is parameterized querying with the injection safety you'd otherwise hand-roll.

You do not have to abandon Prisma's API to get this transport. Driver adapters swap the engine's data layer while keeping the query API:

import { PrismaNeon } from '@prisma/adapter-neon';

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

Alternatively, point datasource at a remote endpoint (prisma://... via Prisma Accelerate or a hosted proxy) and the engine plus pool run outside your process — the client becomes a thin HTTP caller suitable for edge middleware.

Supabase deserves specific knowledge because its connection string hides two different services:

Point Prisma at port 6543 without ?pgbouncer=true and transactions behave strangely or die with prepared-statement errors such as prepared statement "..." already exists, because transaction-mode pooling cannot promise one backend the whole time a statement lives. The flag tells the client to avoid session-scoped assumptions.

What you give up with HTTP: no LISTEN/NOTIFY, no temporary tables, no session SET, and one round trip of TLS per request unless you batch statements into a single call. What you gain is a driver that has no connection state to lose — which is precisely what short-lived code needs.

The comparison is worth carrying into an interview:

Batching is the lever that makes the per-request cost acceptable — several statements travel in one HTTPS call:

const results = await sql.transaction([
  sql`SELECT count(*) FROM "Order" WHERE status = 'PAID'`,
  sql`SELECT sum(total) FROM "Order" WHERE created_at > now() - interval '7 days'`,
]);

If SQL is the wrong level entirely — you want row-level security and REST-shaped CRUD — Supabase's own client (@supabase/supabase-js, PostgREST over HTTPS) is a third option with its own trade-offs. Choose deliberately: the moment you need a CTE or a lock, you are back to the pooler ports.

Run the multiplication before choosing anything: 100 concurrent invocations × a pool of 10 = 1000 connections aimed at a database whose max_connections is 100. Serverless and edge code did not become "stateless" — the state merely moved to wherever you put the pool, and if the answer is "inside each invocation," you have built a connection storm with a cold start.

The invariant: the pool must live in a process that outlives your function. Since your function's lifetime is not under your control, the pool usually lives somewhere you don't run:

Note what the last three have in common: from your code's perspective the pool disappeared — it became somebody's long-lived infrastructure with an SLA. That is the architectural move interviews are fishing for when they ask "how do you connect a serverless function to Postgres?"

Two numbers still deserve attention. Latency is per query now: an edge function in Tokyo talking to a database in Virginia pays ~150 ms each way on every call, so either place the compute near the data (regional functions, read replicas close to users) or accept that edge is for cache-shaped reads. And concurrency limits replace connection limits: the platform caps simultaneous invocations, which quietly becomes your effective database load ceiling — fewer, faster queries matter more than ever, which loops back to include instead of N+1.

A practical routing rule: keep transactions, migrations, and heavy ORM workloads on the Node runtime where pooling and sockets behave conventionally; use the edge for narrow, read-mostly queries with an HTTP driver. Split by route, not by ideology. When you next change table shape, remember migrate deploy belongs in a Node CI job from Applying Schema Migrations; after that, the roadmap moves on to client-side concerns in Local State with useState and useReducer.

If you do run your own pooler, its own limits become your new ceiling, and they fail with messages you should recognize before production teaches you:

ERROR: no more connections allowed (max_client_conn)
ERROR: server pool is at full capacity

PgBouncer's default_pool_size (server connections per user/database) and max_client_conn (client slots in front of them) are the two knobs; SHOW POOLS; in the admin console tells you whether requests are queuing or errors are imminent. Managed poolers expose the equivalent through dashboards — check them, because a pooler that saturates produces the same latency cliff you were avoiding, one layer further from your code.

Warm the paths you care about. With an HTTP driver the first request on a cold instance pays the TLS handshake — usually a few milliseconds — and subsequent calls on the same warm instance reuse that connection through the runtime's fetch implementation, so burst traffic after a cold start is cheap if your queries are few and batched. With a pooled client in Node, await prisma.$connect() at startup moves connection setup out of the first user request. Either way the goal is identical: pay setup costs when the instance boots, not while someone is waiting, and keep the count of queries per request small enough that neither number matters.