neon-serverless

Neon Serverless Driver Guidelines

Overview

This guide provides specific patterns and best practices for connecting to Neon databases in serverless environments using the @neondatabase/serverless driver. The driver connects over HTTP for fast, single queries or WebSockets for node-postgres compatibility and interactive transactions. Follow these guidelines to ensure efficient connections and optimal performance.

Installation

Install the Neon Serverless driver with the correct package name:

# Using npm
npm install @neondatabase/serverless

# Using JSR
bunx jsr add @neon/serverless

Note: The driver version 1.0.0 and higher requires Node.js v19 or later.

For projects that depend on pg but want to use Neon's WebSocket-based connection pool:

"dependencies": {
  "pg": "npm:@neondatabase/serverless@^0.10.4"
},
"overrides": {
  "pg": "npm:@neondatabase/serverless@^0.10.4"
}

Avoid incorrect package names like neon-serverless or pg-neon.

Connection String

Always use environment variables for database connection strings to avoid exposing credentials.

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

// For WebSocket connections
import { Pool } from '@neondatabase/serverless';
const pool = new Pool({ connectionString: process.env.DATABASE_URL! });

Never hardcode credentials in your code:

// AVOID: Hardcoded credentials
const sql = neon('postgres://username:[email protected]/neondb');

Querying with the neon function (HTTP)

The neon() function is ideal for simple, "one-shot" queries in serverless and edge environments as it uses HTTP fetch and is the fastest method for single queries.

Parameterized Queries

Use tagged template literals for safe parameter interpolation. This is the primary defense against SQL injection.

const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;