# Connect an Express application to Neon

Pre-built prompt for connecting ExpressJS applications to Lakebase Postgres

This guide describes how to create a Neon project and connect to it from an Express application to query a Lakebase Postgres database.

## Choose a driver

- **`@neondatabase/serverless`** connects over HTTP or WebSockets instead of TCP. Use it for serverless and edge platforms without built-in connection pooling (Vercel, Netlify Functions, Deno Deploy, Cloudflare Workers without Hyperdrive).
- **`postgres` (postgres.js)** is a fast, full-featured client for both serverless and traditional Node.js server environments.
- **`pg` (node-postgres)** is the classic, widely-used driver for traditional, long-running Node.js servers. Also the standard choice for [Vercel Fluid compute](https://vercel.com/docs/functions/fluid-compute) and Cloudflare with [Hyperdrive](https://developers.cloudflare.com/hyperdrive/).

For a detailed comparison including all platforms, see [Choosing your connection method](/guides/postgres-connect-choose-connection).

:::::steps
:::step{title="Create a Neon project"}
If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.
:::

::::step{title="Create an Express project and add dependencies"}
1. Create an Express project and change to the newly created directory.

   ```bash
   mkdir neon-express-example
   cd neon-express-example
   npm init -y
   npm install express
   ```

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

   :::code-group
   ```bash title="Neon serverless driver"
   npm install @neondatabase/serverless dotenv
   ```

   ```shell title="node-postgres"
   npm install pg dotenv
   ```

   ```shell title="postgres.js"
   npm install postgres dotenv
   ```
   :::
::::

::::step{title="Store your Neon credentials"}
Add a `.env` file to your project directory and add your Neon connection details to it. Find your database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select Node.js from the **Connection string** dropdown. For more information, see [Connect from any application](/guides/postgres-connect-connect-from-any-app).

```bash
DATABASE_URL="postgresql://<user>:<password>@<endpoint_hostname>.neon.tech:<port>/<dbname>?sslmode=require&channel_binding=require"
```

:::callout{intent="note"}
Never hardcode credentials in source code files. Always use environment variables via `process.env`. For more information, see [Security overview](/guides/security-compliance-index).
:::
::::

::::step{title="Configure the Postgres client"}
Add an `index.js` file to your project directory and add the following code snippet to connect to your Neon database:

:::code-group
```javascript title="Neon serverless driver"
require('dotenv').config();

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

const app = express();
const PORT = process.env.PORT || 4242;

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

app.get('/', async (req, res) => {
  try {
    const [result] = await sql`SELECT version()`;
    const version = result?.version || 'No version found';
    res.json({ version });
  } catch (error) {
    console.error('Database query failed:', error);
    res.status(500).json({ error: 'Failed to connect to the database.' });
  }
});

app.listen(PORT, () => {
  console.log(`Listening to http://localhost:${PORT}`);
});
```

```javascript title="node-postgres"
require('dotenv').config();

const express = require('express');
const { Pool } = require('pg');

const app = express();
const PORT = process.env.PORT || 4242;

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

app.get('/', async (req, res) => {
  let client;
  try {
    client = await pool.connect();
    const { rows } = await client.query('SELECT version()');
    const version = rows[0]?.version || 'No version found';
    res.json({ version });
  } catch (error) {
    console.error('Database query failed:', error);
    res.status(500).json({ error: 'Failed to connect to the database.' });
  } finally {
    client?.release();
  }
});

app.listen(PORT, () => {
  console.log(`Listening to http://localhost:${PORT}`);
});
```

```javascript title="postgres.js"
require('dotenv').config();

const express = require('express');
const postgres = require('postgres');

const app = express();
const PORT = process.env.PORT || 4242;

const sql = postgres(process.env.DATABASE_URL);

app.get('/', async (req, res) => {
  try {
    const [result] = await sql`SELECT version()`;
    const version = result?.version || 'No version found';
    res.json({ version });
  } catch (error) {
    console.error('Database query failed:', error);
    res.status(500).json({ error: 'Failed to connect to the database.' });
  }
});

app.listen(PORT, () => {
  console.log(`Listening to http://localhost:${PORT}`);
});
```
:::
::::

:::step{title="Run index.js"}
Run `node index.js` to view the result on localhost:4242 as follows:

```bash
{ version: 'PostgreSQL 16.0 on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit' }
```
:::
:::::

## Connection issues

- If you see an `endpoint ID is not specified` error, the TLS client your Postgres driver depends on doesn't support Server Name Indication (SNI), which Neon uses to route connections. For `pg` (node-postgres), this means an outdated `libpq`-compatible TLS stack; upgrading `pg` usually resolves it.
- If you encounter an `SSL SYSCALL error: EOF detected` (or a similar connection-reset error), this typically happens when an application tries to reuse a connection after the Neon compute has been suspended due to inactivity. This mainly affects long-running servers that keep a connection pool open, like the `pg` example above — closing and recreating idle connections, or reconnecting on error, resolves it.

:::accordion{title="Notes for AI-assisted setup"}
* Do not hardcode credentials or connection strings in any `.js` source file. Always use environment variables via `process.env` and `dotenv`.
* Wrap all database queries in a `try...catch` block. Return a `500` status with an error message on failure.
* When using `pg` (node-postgres), declare `let client` before the `try` block and call `client?.release()` in the `finally` block. This safely handles cases where `pool.connect()` itself fails.
* Initialize the connection pool or client outside the route handler, not inside it. Creating a new pool on every request wastes resources.
* Choose the right driver for your platform. `@neondatabase/serverless` is for serverless/edge platforms without TCP support. For long-running Express servers, use `pg` or `postgres`. See [Choosing your connection method](/guides/postgres-connect-choose-connection).
:::

## Next steps

- [Set up Managed Better Auth](/guides/auth-index): Add managed authentication that branches with your database
- [Add Object Storage](/guides/object-storage-index): S3-compatible file storage that branches with your database
- [Deploy a Function](/guides/neon-functions-index): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](/guides/ai-gateway-index): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Need help?

Join our [Discord Server](https://neon.com/discord) to ask questions or see what others are doing with Neon. For paid plan support options, see [Support](/guides/postgres-introduction-support).

## Related pages

- [Connect Astro to Postgres on Neon](./neon-docs-guides-astro.md)
- [Connect a Bun application to Neon](./neon-docs-guides-bun.md)
- [Connect an Entity Framework application to Neon](./neon-docs-guides-dotnet-entity-framework.md)
- [Connect an Encore application to Neon](./neon-docs-guides-encore.md)
- [Self-Host Medusa with Neon](./neon-docs-guides-medusajs.md)
- [Connect a Micronaut Kotlin application to Lakebase Postgres](./neon-docs-guides-micronaut-kotlin.md)
- [Connect a NestJS application to Neon](./neon-docs-guides-nestjs.md)
- [Connect a Next.js application to Neon](./neon-docs-guides-nextjs.md)
- [Connect a Node.js application to Neon](./neon-docs-guides-node.md)
- [Connect Nuxt to Postgres on Neon](./neon-docs-guides-nuxt.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.