Trying to use a local DB with Vercel Postgres fails due to strict pool URL check

TL;DR

NOTE FROM MAINTAINERS The way to use @vercel/postgres locally is documented here: https://vercel.com/docs/storage/vercel-postgres/local-development --- I thought I could use Vercel Postgres with a local DB for offline development with a custom connection string that points to a local DB......

Steps

1. @vercel/postgres connects through websockets (it is a Neon client), not plain TCP, so pointing it at a local Postgres fails. Two ways around it: follow the documented local-development flow for Vercel Postgres, or run Neon's wsproxy between the client and your local Postgres on port 5432, which one user confirmed works. Also double-check POSTGRES_URL for typos: one reporter's whole issue was a malformed env value.

When to use

You are seeing this: @vercel/postgres connects through websockets (it is a Neon client), not plain TCP, so pointing it at a local Postgres fails. Use this skill when you run into "Trying to use a local DB with Vercel Postgres fails due to strict pool URL check".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Edge cases

• NOTE FROM MAINTAINERS The way to use @vercel/postgres locally is documented here: https://vercel.com/docs/storage/vercel-postgres/local-development --- I thought I could use Vercel Postgres with a local DB for offline development with a custom connection string that points to a local DB......
• Also double-check POSTGRES_URL for typos: one reporter's whole issue was a malformed env value.

Sources

• https://vercel.com/docs/storage/vercel-postgres/local-development

In gh:vercel/storage#123 (https://github.com/vercel/storage/issues/123), the reporter ran into this: NOTE FROM MAINTAINERS The way to use @vercel/postgres locally is documented here: https://vercel.com/docs/storage/vercel-postgres/local-development --- I thought I could use Vercel Postgres with a local DB for offline development with a custom connection string that points to a local DB... ... The verified resolution: @vercel/postgres connects through websockets (it is a Neon client), not plain TCP, so pointing it at a local Postgres fails. Two ways around it: follow the documented local-development flow for Vercel Postgres, or run Neon's wsproxy between the client and your local Postgres on port 5432, which one user confirmed works. Also double-check POSTGRES_URL for typos: one reporter's whole issue was a malformed env value.