@neondatabase/serverless

What is @neondatabase/serverless?

@neondatabase/serverless is an npm package designed to facilitate serverless interactions with Neon, a serverless PostgreSQL database. It provides a set of tools and utilities to connect, query, and manage PostgreSQL databases in a serverless environment, making it easier to build scalable and efficient applications.

What are @neondatabase/serverless's main functionalities?

Connecting to a Neon Database

This feature allows you to establish a connection to a Neon database using the provided connection string. The code sample demonstrates how to create a new client instance and connect to the database.

const { Client } = require('@neondatabase/serverless');

const client = new Client({
  connectionString: process.env.NEON_DATABASE_URL,
});

async function connect() {
  await client.connect();
  console.log('Connected to Neon Database');
}

connect();

Executing SQL Queries

This feature allows you to execute SQL queries against the connected Neon database. The code sample demonstrates how to connect to the database, execute a SELECT query, and log the results.

const { Client } = require('@neondatabase/serverless');

const client = new Client({
  connectionString: process.env.NEON_DATABASE_URL,
});

async function executeQuery() {
  await client.connect();
  const res = await client.query('SELECT * FROM users');
  console.log(res.rows);
  await client.end();
}

executeQuery();

Handling Transactions

This feature allows you to handle transactions in the Neon database. The code sample demonstrates how to begin a transaction, execute an insert query, commit the transaction, and handle errors by rolling back the transaction if necessary.

const { Client } = require('@neondatabase/serverless');

const client = new Client({
  connectionString: process.env.NEON_DATABASE_URL,
});

async function handleTransaction() {
  await client.connect();
  try {
    await client.query('BEGIN');
    await client.query('INSERT INTO users(name) VALUES($1)', ['John Doe']);
    await client.query('COMMIT');
    console.log('Transaction committed');
  } catch (e) {
    await client.query('ROLLBACK');
    console.error('Transaction rolled back', e);
  } finally {
    await client.end();
  }
}

handleTransaction();

Other packages similar to @neondatabase/serverless

pg

The 'pg' package is a popular PostgreSQL client for Node.js. It provides a comprehensive set of features for connecting to and interacting with PostgreSQL databases. Compared to @neondatabase/serverless, 'pg' is more general-purpose and widely used, but it may require additional configuration for serverless environments.

knex

The 'knex' package is a SQL query builder for Node.js, supporting multiple database types including PostgreSQL. It provides a flexible and powerful API for building and executing SQL queries. While 'knex' offers more advanced query building capabilities, it is not specifically tailored for serverless environments like @neondatabase/serverless.

sequelize

The 'sequelize' package is a promise-based Node.js ORM for various SQL databases, including PostgreSQL. It provides a higher-level abstraction for database interactions, including model definitions and associations. Compared to @neondatabase/serverless, 'sequelize' offers more features for complex data modeling but may introduce additional overhead for simple use cases.

README

@neondatabase/serverless [BETA]

@neondatabase/serverless is Neon's PostgreSQL driver for JavaScript and TypeScript. It's:

• Low-latency, thanks to message pipelining and other optimizations
• Ideal for serverless/edge deployment, using https and WebSockets in place of TCP
• A drop-in replacement for node-postgres, aka pg (on which it's based)

Get started

Install it

Install it with your preferred JavaScript package manager. For example:

npm install @neondatabase/serverless

Using TypeScript? No worries: types are included.

Configure it

Get your connection string from the Neon console and set it as an environment variable. Something like:

DATABASE_URL=postgres://username:[e-mail]/neondb

Use it

For one-shot queries, use the neon function. For instance:

import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);

const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
// `post` is now { id: 12, title: 'My post', ... } (or undefined)

Note: interpolating ${postId} here is safe from SQL injection.

Deploy it

Turn this example into a complete API endpoint deployed on Vercel Edge Functions at https://myapp.vercel.dev/api/post?postId=123 by following two simple steps:

1. Create a new file api/post.ts:

import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);

export default async (req: Request, ctx: any) => {
  // get and validate the `postId` query parameter
  const postId = parseInt(new URL(req.url).searchParams.get('postId'), 10);
  if (isNaN(postId)) return new Response('Bad request', { status: 400 });

  // query and validate the post
  const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
  if (!post) return new Response('Not found', { status: 404 });

  // return the post as JSON
  return new Response(JSON.stringify(post), { 
    headers: { 'content-type': 'application/json' }
  });
}

export const config = {
  runtime: 'edge',
  regions: ['iad1'],  // specify the region nearest your Neon DB
};

1. Test and deploy

npm install -g vercel  # install vercel CLI
npx vercel env add DATABASE_URL  # paste Neon connection string, select all environments
npx vercel dev  # check working locally, then ...
npx vercel deploy

The neon query function has a few additional options.

Sessions, transactions, and node-postgres compatibility

A query using the neon function, as shown above, is carried by an https fetch request.

This should work — and work fast — from any modern JavaScript environment. But you can only send one query at a time this way: sessions and transactions are not supported.

transaction()

Multiple queries can be issued via fetch request within a single, non-interactive transaction by using the transaction() function. This is exposed as a property on the query function.

For example:

import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);
const showLatestN = 10;

const [posts, tags] = await sql.transaction([
  sql`SELECT * FROM posts ORDER BY posted_at DESC LIMIT ${showLatestN}`,
  sql`SELECT * FROM tags`,
]);

There are some additional options when using transaction().

Pool and Client

Use the Pool or Client constructors, instead of the functions described above, when you need:

• session or interactive transaction support, and/or

• compatibility with node-postgres, which supports query libraries like Kysely or Zapatos.

Queries using Pool and Client are carried by WebSockets. There are two key things to know about this:

1. In Node.js and some other environments, there's no built-in WebSocket support. In these cases, supply a WebSocket constructor function.

2. In serverless environments such as Vercel Edge Functions or Cloudflare Workers, WebSocket connections can't outlive a single request.

   That means Pool or Client objects must be connected, used and closed within a single request handler. Don't create them 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.

These points are demonstrated in the examples below.

API

• The full API guide to Pool and Client can be found in the node-postgres docs.

• There are a few additional configuration options that apply to Pool and Client here.

Example: Node.js with Pool.connect()

In Node.js, it takes two lines to configure WebSocket support. For example:

import { Pool, neonConfig } from '@neondatabase/serverless';

import ws from 'ws';
neonConfig.webSocketConstructor = ws;  // <-- this is the key bit

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
pool.on('error', err => console.error(err));  // deal with e.g. re-connect
// ...

const client = await pool.connect();

try {
  await client.query('BEGIN');
  const { rows: [{ id: postId }] } = await client.query('INSERT INTO posts (title) VALUES ($1) RETURNING id', ['Welcome']);
  await client.query('INSERT INTO photos (post_id, url) VALUES ($1, $2)', [postId, 's3.bucket/photo/url']);
  await client.query('COMMIT');

} catch (err) {
  await client.query('ROLLBACK');
  throw err;

} finally {
  client.release();
}

// ...
await pool.end();

Other WebSocket libraries are available. For example, you could replace ws in the above example with undici:

import { WebSocket } from 'undici';
neonConfig.webSocketConstructor = WebSocket; 

Example: Vercel Edge Function with Pool.query()

We can rewrite the Vercel Edge Function shown above (under the heading 'Deploy it') to use Pool, as follows:

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

// *don't* create a `Pool` or `Client` here, outside the request handler

export default async (req: Request, ctx: any) => {
  // create a `Pool` inside the request handler
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });

  // get and validate the `postId` query parameter
  const postId = parseInt(new URL(req.url).searchParams.get('postId'), 10);
  if (isNaN(postId)) return new Response('Bad request', { status: 400 });

  // query and validate the post
  const [post] = await pool.query('SELECT * FROM posts WHERE id = $1', [postId]);
  if (!post) return new Response('Not found', { status: 404 });

  // end the `Pool` inside the same request handler 
  // (unlike `await`, `ctx.waitUntil` won't hold up the response)
  ctx.waitUntil(pool.end());

  // return the post as JSON
  return new Response(JSON.stringify(post), { 
    headers: { 'content-type': 'application/json' }
  });
}

export const config = {
  runtime: 'edge',
  regions: ['iad1'],  // specify the region nearest your Neon DB
};

Note: we don't actually use the pooling capabilities of Pool in this example. But it's slightly briefer than using Client and, because Pool.query is designed for one-shot queries, we may in future automatically route these queries over https for lower latency.

Example: Vercel Edge Function with Client

Using Client instead, the example looks like this:

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

// don't create a `Pool` or `Client` here, outside the request handler

export default async (req: Request, ctx: any) => {
  // create a `Client` inside the request handler
  const client = new Client(process.env.DATABASE_URL);
  await client.connect();

  // get and validate the `postId` query parameter
  const postId = parseInt(new URL(req.url).searchParams.get('postId'), 10);
  if (isNaN(postId)) return new Response('Bad request', { status: 400 });

  // query and validate the post
  const [post] = await client.query('SELECT * FROM posts WHERE id = $1', [postId]);
  if (!post) return new Response('Not found', { status: 404 });

  // end the `Client` inside the same request handler 
  // (unlike `await`, `ctx.waitUntil` won't hold up the response)
  ctx.waitUntil(client.end());

  // return the post as JSON
  return new Response(JSON.stringify(post), { 
    headers: { 'content-type': 'application/json' }
  });
}

export const config = {
  runtime: 'edge',
  regions: ['iad1'],  // specify the region nearest your Neon DB
};

More examples

These repos show how to use @neondatabase/serverless with a variety of environments and tools:

• Raw SQL + Vercel Edge Functions
• Raw SQL via https + Vercel Edge Functions
• Raw SQL + Cloudflare Workers
• Kysely + Vercel Edge Functions
• Zapatos + Vercel Edge Functions

Bring your own Postgres database

This package comes configured to connect to a Neon database. But you can also use it to connect to your own Postgres instances if you run your own WebSocket proxy.

Open-source

This code is released under the MIT license.

Feedback and support

Please visit Neon Community or Support.

Changelog

0.9.1 (2024-04-15)

Pass username (and database name) through URL decoder, so all usernames can successfully authorize.