Neon serverless driver
Learn how to connect to Neon from serverless and edge environments over HTTP or WebSockets
The driver's low-latency capability is due to message pipelining and other optimizations.
Install the Neon serverless driver
The driver includes TypeScript types (the equivalent of
@types/pg). No additional installation is required.
Configure your Neon database connection
You can obtain a connection string for your database from the Connection Details widget on the Neon Dashboard and set it as an environment variable. Your Neon connection string will look something like this:
How to use the driver over HTTP
The maximum request size and response size for queries over HTTP is 10 MB. Additionally, there is a 15 second proxy timeout for SQL requests over HTTP. Long running queries that exceed the 15 second threshold are terminated.
Experimental connection caching
Connection caching provides server-side connection pooling, so that a new connection does not have to be set up for each query over HTTP. You can enable it by setting
true in the
Using node-postgres Pool or Client
You can use the Neon serverless driver in the same way you would use
Client. Where you usually import
Client objects must be connected, used, and closed within a single request handler. Don't create the objects outside a request handler; don't create them in one handler and try to reuse them in another; and to avoid exhausting available connections, don't forget to close them.
When to use the neon function vs Pool or Client
The Neon serverless driver supports the
neon function for queries over HTTP, and
Client constructors for querying over WebSockets.
The neon function
Querying over an HTTP fetch request is faster for single, non-interactive transactions. If you do not require sessions or transactions, consider using HTTP for faster response times.
neon function configuration options
neon(...) function supports
fetchOptions option keys for customizing the query function. For usage information, see Options and configuration.
neon(...) function also supports issuing multiple queries at once in a single, non-interactive transaction using the
transaction() function, which is exposed as a property of the query function. For example:
transaction() function supports the same option keys as the ordinary query function —
fetchOptions — plus three additional keys concerning transaction configuration:
Must be one of
Ensures that a
READ ONLYtransaction is used to execute queries. This is a boolean option. The default value is
Ensures that a
DEFERRABLEtransaction is used to execute queries. This is a boolean option. The default value is
For additional details, see transaction(...) function.
Pool or Client
Client constructors, which support querying over WebSockets, provide session and transaction support, as well as
node-postgres compatibility. You can find the API guide for the
Client constructors in the node-postgres documentation.
Consider using the driver with
Client in the following scenarios:
- You already use
node-postgresin your code base and would like to migrate to using
- You are writing a new code base and want to use a package that expects a
- Your backend service uses sessions / interactive transactions with multiple queries per connection.
Pool and Client configuration options
For configuration options that apply to
Client, see options and configuration in the driver's GitHub repository.
Explore the example applications that use the Neon serverless driver.
UNESCO World Heritage sites app
Neon provides an example application to help you get started with the Neon serverless driver. The application generates a
JSON listing of the 10 nearest UNESCO World Heritage sites using IP geolocation (data copyright © 1992 – 2022 UNESCO/World Heritage Centre).
There are different implementations of the application to choose from.
Raw SQL + Vercel Edge Functions
Demonstrates using raw SQL with Neon's serverless driver on Vercel Edge Functions
Raw SQL via https + Vercel Edge Functions
Demonstrates Neon's serverless driver over HTTP on Vercel Edge Functions
Raw SQL + Cloudflare Workers
Demonstrates using the Neon serverless driver on Cloudflare Workers and employs caching for high performance.
Kysely + Vercel Edge Functions
Demonstrates using kysely and kysely-codegen with Neon's serverless driver on Vercel Edge Functions
Zapatos + Vercel Edge Functions
Demonstrates using Zapatos with Neon's serverless driver on Vercel Edge Functions
Demonstrates using Cloudflare's Hyperdrive to access your Neon database from Cloudflare Workers
Neon + Cloudflare Hyperdrive (Beta)
The Ping Thing application pings a Neon Serverless Postgres database using a Vercel Edge Function and shows the journey your request makes. You can read more about this application in the accompanying blog post: How to use Postgres at the Edge
Last updated on