Route the driver through a Docker-hosted proxy on port 5433.
Local Postgres development
Neon · Pipe
wsProxy
wsProxy configures the WebSocket proxy endpoint used by Neon’s serverless driver. A callback can transform the target database host into a proxy URL, which is useful for local Postgres and host-specific routing.
How it works
wsProxy customizes the WebSocket-proxy address used by Neon’s serverless driver. It may be a host string for one proxy or a function that receives the database host and returns the proxy URL, enabling local Postgres or host-dependent routing.
Syntax
neonConfig.wsProxy = string | ((host: string) => string)Parameters
| Name | Type | Description |
|---|---|---|
host | string | A database host passed to the callback so it can construct the WebSocket proxy URL. |
Returns
A WebSocket proxy URL string when wsProxy is configured as a callback.
Key points
- Set wsProxy to a function when the proxy URL should be derived from the target database host.
- The local example turns off secure WebSockets because it connects to a local proxy.
- The local configuration disables pipeline TLS alongside the proxy setting.
- The local configuration also disables pipeline connection setup.
Common mistakes
- A local non-TLS proxy requires secure WebSockets to be disabled.
- Disable pipeline TLS when the local proxy does not provide TLS.
- Disable pipeline connection setup for this local proxy configuration.
Example: Configure a local WebSocket proxy
import { neonConfig } from '@neondatabase/serverless';
neonConfig.wsProxy = (host) => `${host}:5433/v1`;
neonConfig.useSecureWebSocket = false;
neonConfig.pipelineTLS = false;
neonConfig.pipelineConnect = false;Routes the serverless driver through a local WebSocket proxy on port 5433 using the proxy's /v1 path.
When to use it
Choose a proxy URL according to the target database host.
Multiple proxy endpoints
Use a WebSocket proxy to expose a reachable PostgreSQL service to the serverless driver.
Non-Neon PostgreSQL access
Interview questions
QWhat is wsProxy used for?
wsProxy tells the Neon serverless driver which WebSocket proxy to use. It can be a fixed proxy host or a function that derives a proxy URL from the database host.
Follow-up: How would you support different proxy routes by host? Use a function and return a different URL based on the received host, such as adding a port and version path only for local hosts.
QHow do you configure wsProxy for local Postgres?
For a local Postgres setup, the proxy can be addressed by returning the database host with port 5433 and the /v1 path. The driver then sends its WebSocket traffic through that proxy.
Follow-up: What else may need changing locally? Turn off secure WebSockets and the pipeline TLS and connect options when the local proxy configuration requires it.
QWhy use a wsProxy function instead of a string?
The function form receives the target host and returns the proxy endpoint, so routing can vary by destination. This supports setups with distinct proxy addresses or paths rather than one global endpoint.
Follow-up: Why is host-based routing useful? It allows local and remote database hosts to use different proxy URLs while sharing the same driver configuration.
Related
neonConfig.useSecureWebSocketneonConfig.pipelineTLSneonConfig.pipelineConnect@neondatabase/serverless