Connect a Node.js application to Neon
Set up a Neon project in seconds and connect from a Node.js application
Pre-built prompt for connecting Node.js applications to Neon. View prompt
This guide describes how to create a Neon project and connect to it from a Node.js application. Examples are provided for using the node-postgres and Postgres.js clients. Use the client you prefer.
Note: The same configuration steps can be used for Express and Next.js applications.
To connect to Neon from a Node.js application:
Create a Neon project
Section titled “Create a Neon project”If you do not have one already, create a Neon project.
- Navigate to the Projects page in the Neon Console.
- Click New Project.
- Specify your project settings and click Create Project.
Create a NodeJS project and add dependencies
Section titled “Create a NodeJS project and add dependencies”-
Create a NodeJS project and change to the newly created directory.
Shell mkdir neon-nodejs-example cd neon-nodejs-example npm init -y -
Add project dependencies using one of the following commands:
Neon serverless driver
Shell npm install @neondatabase/serverless dotenvnode-postgres
Shell npm install pg dotenvpostgres.js
Shell npm install postgres dotenv
Store your Neon credentials
Section titled “Store your Neon credentials”Add a .env file to your project directory and add your Neon connection details to it. You can find your Neon database connection details by clicking the Connect button in the Console nav to open the Connect to your branch modal. Please select Node.js from the Connection string dropdown. For more information, see Connect from any application.
PGHOST='[neon_hostname]'
PGDATABASE='[dbname]'
PGUSER='[user]'
PGPASSWORD='[password]'
ENDPOINT_ID='[endpoint_id]'Note: A special ENDPOINT_ID variable is included in the .env file above. This variable can be used with older Postgres clients that do not support Server Name Indication (SNI), which Neon relies on to route incoming connections. If you are using a newer node-postgres or postgres.js client, you won't need it. For more information, see Endpoint ID variable.
Important: To ensure the security of your data, never expose your Neon credentials to the browser.
Configure the Postgres client
Section titled “Configure the Postgres client”Add an app.js file to your project directory and add the following code snippet to connect to your Neon database:
Neon serverless driver
require('dotenv').config();
const { neon } = require('@neondatabase/serverless');
const { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;
const sql = neon(
`postgresql://${PGUSER}:${PGPASSWORD}@${PGHOST}/${PGDATABASE}?sslmode=require&channel_binding=require`
);
async function getPgVersion() {
const result = await sql`SELECT version()`;
console.log(result[0]);
}
getPgVersion();node-postgres
require('dotenv').config();
const { Pool } = require('pg');
const { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;
const pool = new Pool({
host: PGHOST,
database: PGDATABASE,
username: PGUSER,
password: PGPASSWORD,
port: 5432,
ssl: {
require: true,
},
});
async function getPgVersion() {
const client = await pool.connect();
try {
const result = await client.query('SELECT version()');
console.log(result.rows[0]);
} finally {
client.release();
}
}
getPgVersion();postgres.js
require('dotenv').config();
const postgres = require('postgres');
const { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;
const sql = postgres({
host: PGHOST,
database: PGDATABASE,
username: PGUSER,
password: PGPASSWORD,
port: 5432,
ssl: 'require',
});
async function getPgVersion() {
const result = await sql`select version()`;
console.log(result[0]);
}
getPgVersion();Option 4
require('dotenv').config();
const { Pool } = require('pg');
let { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;
const pool = new Pool({
host: PGHOST,
database: PGDATABASE,
username: PGUSER,
password: PGPASSWORD,
port: 5432,
ssl: {
require: true,
},
});
async function getPgVersion() {
const client = await pool.connect();
try {
const result = await client.query('SELECT version()');
console.log(result.rows[0]);
} finally {
client.release();
}
}
getPgVersion();Option 5
require('dotenv').config();
const postgres = require('postgres');
let { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;
const sql = postgres({
host: PGHOST,
database: PGDATABASE,
username: PGUSER,
password: PGPASSWORD,
port: 5432,
ssl: 'require',
});
async function getPgVersion() {
const result = await sql`select version()`;
console.log(result[0]);
}
getPgVersion();Run app.js
Section titled “Run app.js”Run node app.js to view the result.
{
version: 'PostgreSQL 16.0 on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit'
}Endpoint ID variable
Section titled “Endpoint ID variable”For older clients that do not support Server Name Indication (SNI), the postgres.js example below shows how to include the ENDPOINT_ID variable in your application's connection configuration. This is a workaround that is not required if you are using a newer node-postgres or postgres.js client. For more information about this workaround and when it is required, see The endpoint ID is not specified in our connection errors documentation.
// app.js
require('dotenv').config();
const postgres = require('postgres');
const { PGHOST, PGDATABASE, PGUSER, PGPASSWORD, ENDPOINT_ID } = process.env;
const sql = postgres({
host: PGHOST,
database: PGDATABASE,
username: PGUSER,
password: PGPASSWORD,
port: 5432,
ssl: 'require',
connection: {
options: `project=${ENDPOINT_ID}`,
},
});
async function getPgVersion() {
const result = await sql`select version()`;
console.log(result);
}
getPgVersion();Community resources
Section titled “Community resources”Next steps
Section titled “Next steps”- Set up Managed Better Auth: Add managed authentication that branches with your database
- Add Object Storage: S3-compatible file storage that branches with your database
- Deploy a Function: Run backend compute next to your database, no separate hosting needed
- Call an LLM with AI Gateway: Access foundation models from Anthropic, OpenAI, Google, and more with one credential