Connect a Node.js application to Neon

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.

To connect to Neon from a Node.js application:

1. Create a Neon Project
2. Create a NodeJS project and add dependencies
3. Store your Neon credentials
4. Configure the Postgres client
5. Run app.js

Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the Projects page in the Neon Console.
2. Click New Project.
3. Specify your project settings and click Create Project.

Create a NodeJS project and add dependencies

1. Create a NodeJS project and change to the newly created directory.

   mkdir neon-nodejs-example
   cd neon-nodejs-example
   npm init -y

2. Add project dependencies using one of the following commands:

   node-postgres

   postgres.js

   npm install pg dotenv

Store your Neon credentials

Add a .env file to your project directory and add your Neon connection details to it. You can find the connection details for your database in the Connection Details widget on the Neon Dashboard. 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]'

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:

const { Pool } = require('pg');
require('dotenv').config();

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();

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

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
const postgres = require('postgres');
require('dotenv').config();

let { 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

• Serverless Node.js Tutorial – Neon Serverless Postgres, AWS Lambda, Next.js, Vercel