Skip to main content
PlanetScale supports connections via the Neon serverless driver. This is a good option for connecting to your PlanetScale database in serverless environments like Vercel Functions or AWS Lambda. You can find detailed documentation on Neon’s website or on the GitHub repository.

​
HTTP vs WebSocket modes

The Neon serverless driver supports two connection modes:
  • HTTP mode — Uses the neon function to execute queries over HTTP. Faster for single queries and non-interactive transactions. No connection state is maintained between requests.
  • WebSocket mode — Uses the Pool object to establish a WebSocket connection. Required for session support, interactive transactions, or node-postgres compatibility.
PlanetScale supports both modes. Choose based on your use case:
Use caseRecommended mode
Single queriesHTTP
Non-interactive transactions (batch of queries)HTTP
Interactive transactionsWebSocket
Session-based featuresWebSocket
node-postgres compatibilityWebSocket

​
Setting up credentials

Both modes use the same credentials setup.
1
Install the driver via npm:
npm install @neondatabase/serverless
2
You’ll need to create a Postgres role to use with the driver. Once you have these credentials, place them in environment variables:
DATABASE_HOST=XXXX.pg.psdb.cloud
DATABASE_PORT=5432
DATABASE_NAME=XXXX
DATABASE_USERNAME=XXXX
DATABASE_PASSWORD=pscale_pw_XXXX
These can all be added to a unified Postgres connection URL for use by the driver:
DATABASE_URL="postgresql://$DATABASE_USERNAME:$DATABASE_PASSWORD@$DATABASE_HOST:$DATABASE_PORT/$DATABASE_NAME"

​
Using HTTP mode

HTTP mode is the simplest way to execute queries. You must configure the fetchEndpoint to use PlanetScale’s SQL endpoint. 
import { neon, neonConfig } from "@neondatabase/serverless";

// This MUST be set for PlanetScale Postgres connections
neonConfig.fetchEndpoint = (host) => `https://${host}/sql`;

const sql = neon(process.env.DATABASE_URL!);

const posts = await sql`SELECT * FROM posts WHERE id = ${postId}`;
The neon function returns a tagged template literal that automatically handles parameterized queries, protecting against SQL injection. See Neon’s HTTP mode documentation for additional configuration options.

​
Non-interactive transactions

HTTP mode supports non-interactive transactions where you send a batch of queries to be executed together. Use the transaction function: 
import { neon, neonConfig } from "@neondatabase/serverless";

// This MUST be set for PlanetScale Postgres connections
neonConfig.fetchEndpoint = (host) => `https://${host}/sql`;

const sql = neon(process.env.DATABASE_URL!);

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

​
Using WebSocket mode

WebSocket mode provides a full Pool interface compatible with the pg library. See Neon’s WebSocket documentation for the full API reference. This mode requires additional configuration for PlanetScale connections.
1
When connecting, you must set the following configuration options:
neonConfig.pipelineConnect = false;
neonConfig.wsProxy = (host, port) => `${host}/v2?address=${host}:${port}`;
2
Here’s a complete example:
import ws from "ws";
import { Pool, neonConfig } from "@neondatabase/serverless";

neonConfig.webSocketConstructor = ws;
// These MUST be set for PlanetScale Postgres connections
neonConfig.pipelineConnect = false;
neonConfig.wsProxy = (host, port) => `${host}/v2?address=${host}:${port}`;

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const posts = await pool.query("SELECT * FROM posts WHERE id = $1", [postId]);

pool.end();
In browser or edge environments that have a native WebSocket global, you don’t need to import ws or set neonConfig.webSocketConstructor.

​
Security

PlanetScale requires SCRAM-SHA-256 for all authentication to Postgres servers. We maintain this strict requirement for security purposes. For WebSocket connections, you must set neonConfig.pipelineConnect = false;. This adds a bit of additional latency, but is necessary to connect using SCRAM-SHA-256. When this is "password" (the default value) it requires using cleartext password authentication, reducing connection security. HTTP mode connections handle authentication automatically and don’t require this configuration.