Connect a Next.js application to Neon

Next.js by Vercel is an open source web development framework that enables React based web applications. This topic describes how to create a Neon project and access it from a Next.js application. Vid...

Pre-built prompt for connecting Next.js applications to Neon

Next.js by Vercel is an open-source web development framework that enables React-based web applications. This topic describes how to create a Neon project and access it from a Next.js application.

Video walkthrough

Watch Getting started with Neon for an end-to-end setup with Next.js and Drizzle.

https://www.youtube.com/embed/XtMiMnX0hDg

To create a Neon project and access it from a Next.js application:

Create a Neon project
If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.
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 Next.js project and add dependencies
1. Create a Next.js project if you do not have one. For instructions, see Create a Next.js App, in the Vercel documentation.
2. Add project dependencies using one of the following commands. If you're not sure which to use, use @neondatabase/serverless: it connects over HTTP instead of TCP, which works in Next.js Edge Functions and other environments without TCP support, and needs no extra SSL configuration.npm install @neondatabase/serverlessnpm install postgresnpm install pg
Store your Neon credentials
Add a .env.local file to your project directory and add your Neon connection string to it. You can find your Neon database connection string by clicking the Connect button in the Console nav to open the Connect to your branch modal. For more information, see Connect from any application.
Bash
```
DATABASE_URL="postgresql://<user>:<password>@<endpoint_hostname>.neon.tech:<port>/<dbname>?sslmode=require&channel_binding=require"
```

Configure the Postgres client

There are multiple ways to make server side requests with Next.js. See below for the different implementations.

App Router

There are two methods for fetching and mutating data using server-side requests in Next.js App Router, they are:

Server Components fetches data at runtime on the server.
Server Actions functions executed on the server to perform data mutations.

Server Components

In your server components using the App Router, add the following code snippet to connect to your Neon database:

Neon serverless driver (Recommended)

import { neon } from '@neondatabase/serverless';

async function getData() {
  const sql = neon(process.env.DATABASE_URL);
  const response = await sql`SELECT version()`;
  return response[0].version;
}

export default async function Page() {
  const data = await getData();
  return <>{data}</>;
}

postgres.js

import postgres from 'postgres';

async function getData() {
  const sql = postgres(process.env.DATABASE_URL, { ssl: 'require' });
  const response = await sql`SELECT version()`;
  return response[0].version;
}

export default async function Page() {
  const data = await getData();
  return <>{data}</>;
}

node-postgres

import { Pool } from 'pg';

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

async function getData() {
  const client = await pool.connect();
  try {
    const { rows } = await client.query('SELECT version()');
    return rows[0].version;
  } finally {
    client.release();
  }
}

export default async function Page() {
  const data = await getData();
  return <>{data}</>;
}

Understanding Caching in Server Components

The examples above will work in development, but in production builds, Next.js will statically render these pages at build time. This means the database query runs once during build, not on every request.

If you need fresh data on each request, add this to your page:

TypeScript

export const dynamic = 'force-dynamic';

For other scenarios like periodic updates, see Time-based Revalidation in the Next.js docs.

Server Actions

In your server actions using the App Router, add the following code snippet to connect to your Neon database:

Neon serverless driver (Recommended)

import { neon } from '@neondatabase/serverless';

export default async function Page() {
  async function create(formData: FormData) {
    "use server";
    const sql = neon(process.env.DATABASE_URL);
    await sql`CREATE TABLE IF NOT EXISTS comments (comment TEXT)`;
    const comment = formData.get("comment");
    await sql`INSERT INTO comments (comment) VALUES (${comment})`;
  }
  return (
    <form action={create}>
      <input type="text" placeholder="write a comment" name="comment" />
      <button type="submit">Submit</button>
    </form>
  );
}

postgres.js

import postgres from 'postgres';

export default async function Page() {
  async function create(formData: FormData) {
    "use server";
    const sql = postgres(process.env.DATABASE_URL, { ssl: 'require' });
    await sql`CREATE TABLE IF NOT EXISTS comments (comment TEXT)`;
    const comment = formData.get("comment");
    await sql`INSERT INTO comments (comment) VALUES (${comment})`;
  }
  return (
    <form action={create}>
      <input type="text" placeholder="write a comment" name="comment" />
      <button type="submit">Submit</button>
    </form>
  );
}

node-postgres

import { Pool } from 'pg';

export default async function Page() {
  async function create(formData: FormData) {
    "use server";
    const pool = new Pool({
      connectionString: process.env.DATABASE_URL,
      ssl: true
    });
    const client = await pool.connect();
    await client.query("CREATE TABLE IF NOT EXISTS comments (comment TEXT)");
    const comment = formData.get("comment");
    await client.query("INSERT INTO comments (comment) VALUES ($1)", [comment]);
  }
  return (
    <form action={create}>
      <input type="text" placeholder="write a comment" name="comment" />
      <button type="submit">Submit</button>
    </form>
  );
}

Pages Router

There are two methods for fetching data using server-side requests in Next.js Pages Router, they are:

getServerSideProps fetches data at runtime so that content is always fresh.
getStaticProps pre-renders pages at build time for data that is static or changes infrequently.

getServerSideProps

From getServerSideProps using the Pages Router, add the following code snippet to connect to your Neon database:

Neon serverless driver (Recommended)

import { neon } from '@neondatabase/serverless';

export async function getServerSideProps() {
  const sql = neon(process.env.DATABASE_URL);
  const response = await sql`SELECT version()`;
  return { props: { data: response[0].version } };
}

export default function Page({ data }) {
  return <>{data}</>;
}

postgres.js

import postgres from 'postgres';

export async function getServerSideProps() {
  const sql = postgres(process.env.DATABASE_URL, { ssl: 'require' });
  const response = await sql`SELECT version()`;
  return { props: { data: response[0].version } };
}

export default function Page({ data }) {
  return <>{data}</>;
}

node-postgres

import { Pool } from 'pg';

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

export async function getServerSideProps() {
  const client = await pool.connect();
  try {
    const response = await client.query('SELECT version()');
    return { props: { data: response.rows[0].version } };
  } finally {
    client.release();
  }
}

export default function Page({ data }) {
  return <>{data}</>;
}

getStaticProps

From getStaticProps using the Pages Router, add the following code snippet to connect to your Neon database:

Neon serverless driver (Recommended)

import { neon } from '@neondatabase/serverless';

export async function getStaticProps() {
  const sql = neon(process.env.DATABASE_URL);
  const response = await sql`SELECT version()`;
  return { props: { data: response[0].version } };
}

export default function Page({ data }) {
  return <>{data}</>;
}

postgres.js

import postgres from 'postgres';

export async function getStaticProps() {
  const sql = postgres(process.env.DATABASE_URL, { ssl: 'require' });
  const response = await sql`SELECT version()`;
  return { props: { data: response[0].version } };
}

export default function Page({ data }) {
  return <>{data}</>;
}

node-postgres

import { Pool } from 'pg';

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

export async function getStaticProps() {
  const client = await pool.connect();
  try {
    const response = await client.query('SELECT version()');
    return { props: { data: response.rows[0].version } };
  } finally {
    client.release();
  }
}

export default function Page({ data }) {
  return <>{data}</>;
}

Serverless Functions

From your Serverless Functions, add the following code snippet to connect to your Neon database:

Neon serverless driver (Recommended)

import { neon } from '@neondatabase/serverless';

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

export default async function handler(req, res) {
  const response = await sql`SELECT version()`;
  const { version } = response[0];
  res.status(200).json({ version });
}

postgres.js

import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL, { ssl: 'require' });

export default async function handler(req, res) {
  const response = await sql`SELECT version()`;
  const { version } = response[0];
  res.status(200).json({ version });
}

node-postgres

import { Pool } from 'pg';

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

export default async function handler(req, res) {
  const client = await pool.connect();
  try {
    const { rows } = await client.query('SELECT version()');
    const { version } = rows[0];
    res.status(200).json({ version });
  } finally {
    client.release();
  }
}

Edge Functions

From your Edge Functions, add the following code snippet and connect to your Neon database using the Neon serverless driver:

JavaScript

export const config = {
  runtime: 'edge',
};

import { neon } from '@neondatabase/serverless';

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

export default async function handler(req: Request) {
  const response = await sql`SELECT version()`;
  const { version } = response[0];
  return Response.json({ version });
}

Run the app

When you run npm run dev you can expect to see the following on localhost:3000:

Bash

PostgreSQL 17.7 on aarch64-unknown-linux-gnu, compiled by gcc (Debian 12.2.0-14+deb12u1) 12.2.0, 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 the pg and postgres.js examples above when used outside a serverless request lifecycle, since they can hold a connection open; reconnecting on error resolves it. @neondatabase/serverless isn't affected, since it opens a new HTTP connection per query.

Where to upload and serve files?

Neon does not provide a built-in file storage service. For managing binary file data (blobs), we recommend using dedicated, specialized storage services. Follow our guide on File Storage to learn more about how to store files in external object storage and file management services and track metadata in Neon.

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

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.

Search documentation

Neon Docs

Connect a Next.js application to Neon

Video walkthrough

App Router

Server Components

Understanding Caching in Server Components

Server Actions

Pages Router

getServerSideProps

getStaticProps

Serverless Functions

Edge Functions

Connection issues

Where to upload and serve files?

Next steps

Need help?

Neon Docs