Powering next gen AI apps with Postgres 🚀 Learn More
Neon
Star usSign up
Guides/Serverless

Neon serverless driver

Learn how to connect to Neon from serverless and edge environments over HTTP or WebSockets

The Neon serverless driver is a low-latency Postgres driver for JavaScript and TypeScript that allows you to query data from serverless and edge environments over HTTP or WebSockets in place of TCP.

You can use the driver as a drop-in replacement for node-postgres, the popular npm pg package you may already be familiar with. See Using node-postgres Pool or Client.

The driver's low-latency capability is due to message pipelining and other optimizations.

Install the Neon serverless driver

You can install the driver with your preferred JavaScript package manager. For example:

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

To use the Neon serverless driver over HTTP, you must use the driver's neon function. You can use raw SQL queries or tools such as Drizzle-ORM, kysely, Zapatos, and others for type safety.

Node.js
Drizzle-ORM
Vercel Edge Function
Vercel Serverless Function

note

The maximum response size for queries over HTTP is 10 MB.

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 fetchConnectionCache to true in the neonConfig object.

Using node-postgres Pool or Client

You can use the Neon serverless driver in the same way you would use node-postgres with Pool and Client. Where you usually import pg, import @neondatabase/serverless instead.

note

The Pool and 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.

Node.js
Drizzle-ORM
Vercel Edge Function
Vercel Serverless Function

When to use the neon function vs Pool or Client

The Neon serverless driver supports the neon function for queries over HTTP, and Pool 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

The neon(...) function supports arrayMode, fullResults, and fetchOptions option keys for customizing the query function. For usage information, see Options and configuration.

The 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:

The transaction() function supports the same option keys as the ordinary query function — arrayMode, fullResults, and fetchOptions — plus three additional keys concerning transaction configuration:

  • isolationMode

    Must be one of ReadUncommitted, ReadCommitted, RepeatableRead, or Serializable.

  • readOnly

    Ensures that a READ ONLY transaction is used to execute queries. This is a boolean option. The default value is false.

  • deferrable

    Ensures that a DEFERRABLE transaction is used to execute queries. This is a boolean option. The default value is false.

For additional details, see transaction(...) function.

Pool or Client

The Pool and 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 Pool and Client constructors in the node-postgres documentation.

Consider using the driver with Pool or Client in the following scenarios:

  • You already use node-postgres in your code base and would like to migrate to using @neondatabase/serverless.
  • You are writing a new code base and want to use a package that expects a node-postgres-compatible driver.
  • Your backend service uses sessions / interactive transactions with multiple queries per connection.

Pool and Client configuration options

For configuration options that apply to Pool and Client, see options and configuration in the driver's GitHub repository.

Example application

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).

UNESCO World Heritage sites app

There are different implementations of the application to choose from.

PreviousWunderGraph
NextAWS Lambda
Edit this page
Was this page helpful?