How to Connect Next.js to Neon Database

Neon is a serverless PostgreSQL platform and Next.js is the most popular React framework for full-stack development. Together they form one of the most powerful and developer-friendly stacks available in 2026 — scalable, fast, and free to start. This guide walks you through everything from creating your first Neon project to building production-ready query patterns, integrating Prisma, handling migrations, deploying to Vercel, and keeping your database secure.

Why Neon + Next.js Is a Great Combination

Before diving into the setup, it is worth understanding why this combination has become so popular. Traditional PostgreSQL databases require you to manage a persistent server — provisioning, scaling, paying for compute even when idle, and handling connection limits carefully. Neon removes all of that. It's serverless Postgres: the database scales to zero when not in use, wakes up automatically when a query arrives, and charges you only for the compute you actually consume.

This aligns perfectly with how Next.js works. When you deploy a Next.js app to Vercel, your Server Components, API Routes, and Server Actions all run as serverless functions — short-lived processes that spin up per request. A traditional database connection pool does not work well in this environment because serverless functions can't maintain persistent connections between invocations. Neon's serverless driver solves this by using HTTP-based queries that are stateless and edge-compatible, making it the ideal database layer for a serverless Next.js deployment.

Pre-requisites

Before following this guide, make sure you have the following in place. If you are missing any of these, the links below will help you get set up quickly.

• Node.js 18+ and npm or pnpm installed on your machine
• A basic Next.js app using the App Router (recommended) or Pages Router
• A Neon account — sign up free at neon.tech. No credit card required for the free tier.
• Basic familiarity with PostgreSQL — you do not need to be an expert, but understanding tables, rows, and SQL queries will help
• Optional: A Vercel account if you plan to deploy (the Neon integration with Vercel is smooth)

Step 1: Create a Neon Project and Database

The first step is creating your Neon project, which provisions a serverless PostgreSQL database in seconds. Unlike traditional database setup, there is no server to configure, no storage volume to allocate, and no firewall rules to set up manually. Neon handles all of that for you.

1. Navigate to neon.tech and sign in or create a free account.
2. Click New Project. Give your project a name — something like my-nextjs-app.
3. Choose your preferred cloud region. For lowest latency, pick the region closest to where your Next.js app will be deployed (e.g., US East for Vercel's default region).
4. Neon will provision a PostgreSQL database with a default branch called main, a default database named neondb, and a default role.
5. Click the Connect button in the project dashboard to find your connection details.

You'll see several connection options in the dashboard: a direct connection string, a pooled connection string, and environment variable snippets ready to paste. We'll use all of these at different stages of this guide.

postgresql://USER:PASSWORD@YOUR-HOST.neon.tech/DBNAME?sslmode=require

postgresql://USER:PASSWORD@YOUR-HOST-pooler.neon.tech/DBNAME?sslmode=require&pgbouncer=true

Step 2: Create or Open Your Next.js App

If you do not already have a Next.js project, create one using the official CLI. The App Router (introduced in Next.js 13 and now the default) is recommended for new projects because it works smoothly with React Server Components, which are the best place to run database queries in a Next.js application.

npx create-next-app@latest my-neon-app
cd my-neon-app

If you already have an existing Next.js project, simply open it in your editor and continue from Step 3. The Neon driver works with both the App Router and Pages Router, though the code examples in this guide use the App Router.

Step 3: Install the Neon Serverless Driver

Neon provides an official serverless driver that is purpose-built for edge and serverless environments. Unlike the standard pg Node.js driver, which uses persistent TCP connections and does not work well in serverless functions, the Neon driver uses HTTP and WebSockets to communicate with the database. This makes it stateless, fast to initialize, and compatible with Vercel's Edge Runtime if needed.

npm install @neondatabase/serverless

pnpm add @neondatabase/serverless

The @neondatabase/serverless package exports a neon function that accepts your connection string and returns a tagged template literal query interface. This interface lets you write SQL queries with interpolated variables in a way that is safe from SQL injection by default — the driver automatically parameterizes your values.

Step 4: Configure Environment Variables

Environment variables are the secure way to store your database connection string without hardcoding it into your source code. Next.js reads a .env.local file automatically during development, and environment variables set in your deployment platform (like Vercel) are used in production.

# Direct connection — use for migrations and Prisma introspection
DATABASE_URL="postgresql://USER:PASSWORD@YOUR-HOST.neon.tech/DBNAME?sslmode=require"

# Pooled connection — use for application queries in production
DATABASE_URL_UNPOOLED="postgresql://USER:PASSWORD@YOUR-HOST-pooler.neon.tech/DBNAME?sslmode=require&pgbouncer=true"

In Next.js, environment variables are only available on the server by default. To use them in Server Components, Server Actions, and API Routes, you reference them with process.env.DATABASE_URL. If you ever need an environment variable on the client side (browser), you must prefix it with NEXT_PUBLIC_ — but never expose your database credentials on the client.

# .gitignore
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

Step 5: Query Neon from a Server Component

React Server Components (RSC) are the ideal place to run database queries in the Next.js App Router. They run exclusively on the server, never in the browser, which means your database credentials and query logic are never exposed to the client. They also support async/await at the top level, making it clean to fetch data and render it in the same component without any client-side state or loading effects.

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

async function getVersion(): Promise<string> {
  const sql = neon(process.env.DATABASE_URL!);
  const rows = await sql`SELECT version()`;
  return rows[0].version as string;
}

export default async function HomePage() {
  const version = await getVersion();
  return (
    <main style={{ padding: '2rem' }}>
      <h1>Connected to Neon! “&</h1>
      <p>PostgreSQL version: {version}</p>
    </main>
  );
}

Notice how clean this is. There's no useEffect, no loading state, no client-side fetch. The component is an async function that awaits the database query directly. The rendered HTML is sent to the browser already populated with data — which also means better SEO and faster perceived load times.

Querying a real table

Let us extend this to query actual application data. First, create a table in Neon using the SQL editor in the Neon dashboard or by running a query:

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

type Post = {
  id: number;
  title: string;
  body: string;
  created_at: string;
};

async function getPosts(): Promise<Post[]> {
  const sql = neon(process.env.DATABASE_URL!);
  const rows = await sql`
    SELECT id, title, body, created_at
    FROM posts
    ORDER BY created_at DESC
    LIMIT 10
  `;
  return rows as Post[];
}

export default async function PostsPage() {
  const posts = await getPosts();
  return (
    <main style={{ padding: '2rem' }}>
      <h1>Latest Posts</h1>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.body}</p>
          <small>{new Date(post.created_at).toLocaleDateString()}</small>
        </article>
      ))}
    </main>
  );
}

Step 6: Query from a Server Action

Server Actions are Next.js's mechanism for running server-side code in response to user interactions — form submissions, button clicks, and mutations. They are defined with the 'use server' directive and can be called directly from a Client or Server Component without building a separate API endpoint. Combined with Neon, they make it trivially easy to build forms that write to your database.

import { neon } from '@neondatabase/serverless';
import { revalidatePath } from 'next/cache';

async function createPost(formData: FormData) {
  'use server';

  const title = formData.get('title') as string;
  const body = formData.get('body') as string;

  // Basic validation
  if (!title?.trim() || !body?.trim()) {
    throw new Error('Title and body are required');
  }

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

  // Parameterised — safe from SQL injection
  await sql`
    INSERT INTO posts (title, body, created_at)
    VALUES (${title}, ${body}, NOW())
  `;

  // Revalidate the posts page so it shows the new post
  revalidatePath('/posts');
}

export default function NewPostForm() {
  return (
    <form action={createPost}>
      <input name="title" placeholder="Post title" required />
      <textarea name="body" placeholder="Write your post..." required />
      <button type="submit">Publish Post</button>
    </form>
  );
}

Notice the call to revalidatePath('/posts') after the insert. This tells Next.js to invalidate the cached version of the /posts route so that the next visitor sees the freshly updated data. Without this, Next.js would continue serving the cached page even after the new post was inserted.

Step 7: Query from an API Route

Sometimes you need a traditional REST API endpoint — for use by a mobile client, a third-party service, or a part of your frontend that uses client-side fetching. Next.js App Router API Routes (called Route Handlers) let you define these alongside your pages. They run on the server and have full access to your environment variables and Neon connection.

import { neon } from '@neondatabase/serverless';
import { NextResponse } from 'next/server';

export async function GET() {
  try {
    const sql = neon(process.env.DATABASE_URL!);
    const posts = await sql`
      SELECT id, title, body, created_at
      FROM posts
      ORDER BY created_at DESC
    `;
    return NextResponse.json({ posts }, { status: 200 });
  } catch (error) {
    console.error('Database error:', error);
    return NextResponse.json(
      { error: 'Failed to fetch posts' },
      { status: 500 }
    );
  }
}

import { neon } from '@neondatabase/serverless';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    const { title, content } = body;

    if (!title || !content) {
      return NextResponse.json(
        { error: 'Title and content are required' },
        { status: 400 }
      );
    }

    const sql = neon(process.env.DATABASE_URL!);
    const result = await sql`
      INSERT INTO posts (title, body, created_at)
      VALUES (${title}, ${content}, NOW())
      RETURNING id, title, created_at
    `;

    return NextResponse.json({ post: result[0] }, { status: 201 });
  } catch (error) {
    console.error('Database error:', error);
    return NextResponse.json(
      { error: 'Failed to create post' },
      { status: 500 }
    );
  }
}

Step 8: Set Up Prisma with Neon

While the raw Neon driver is great for simple queries, most production applications benefit from using an ORM. Prisma is the most popular ORM in the Next.js ecosystem and integrates with Neon using a dedicated connection adapter. Prisma gives you type-safe queries based on your database schema, automatic TypeScript type generation, and a powerful migration system.

npm install prisma @prisma/client @prisma/adapter-neon @neondatabase/serverless ws
npm install -D @types/ws

npx prisma init

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DATABASE_URL_UNPOOLED")
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  body      String
  published Boolean  @default(false)
  author    User?    @relation(fields: [authorId], references: [id])
  authorId  Int?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
}

import { PrismaClient } from '@prisma/client';
import { PrismaNeon } from '@prisma/adapter-neon';
import { neonConfig, Pool } from '@neondatabase/serverless';
import ws from 'ws';

// Required for Node.js environments (not needed on Vercel Edge)
neonConfig.webSocketConstructor = ws;

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

function createPrismaClient() {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const adapter = new PrismaNeon(pool);
  return new PrismaClient({ adapter });
}

export const prisma = globalForPrisma.prisma ?? createPrismaClient();

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma;
}

import { prisma } from '@/lib/prisma';

export default async function PostsPage() {
  const posts = await prisma.post.findMany({
    where: { published: true },
    include: { author: true },
    orderBy: { createdAt: 'desc' },
    take: 10,
  });

  return (
    <main>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>By {post.author?.name ?? 'Anonymous'}</p>
        </article>
      ))}
    </main>
  );
}

Step 9: Running and Testing Migrations

Prisma Migrate handles schema changes through versioned migration files. When you modify your schema.prisma, you generate a migration that contains the SQL to update your database, and Prisma applies it in order. This gives you a full history of schema changes and makes it safe to evolve your database alongside your application code.

# Generate migration SQL and apply it to your Neon database
npx prisma migrate dev --name init

# Generate the Prisma client based on your schema
npx prisma generate

import { prisma } from '../lib/prisma';

async function main() {
  await prisma.user.create({
    data: {
      email: 'alice@example.com',
      name: 'Alice',
      posts: {
        create: [
          { title: 'Hello Neon', body: 'My first post!', published: true },
          { title: 'Draft post', body: 'Coming soon...', published: false },
        ],
      },
    },
  });
  console.log('Seed complete');
}

main()
  .catch(console.error)
  .finally(() => prisma.$disconnect());

"prisma": {
  "seed": "ts-node --compiler-options {\"module\":\"CommonJS\"} prisma/seed.ts"
}

npx prisma db seed

Step 10: Connection Pooling for Production

PostgreSQL has a hard limit on the number of simultaneous connections. In a serverless environment where dozens or hundreds of function instances may spin up simultaneously, each trying to open its own database connection, you can quickly hit this limit and get connection refused errors. Neon's built-in PgBouncer connection pooler solves this by maintaining a pool of connections to the database and multiplexing many application requests through them.

To use the pooler, you simply use the pooled connection string (which ends in -pooler.neon.tech) for your application queries. For Prisma migrations and schema introspection, you must use the direct (non-pooled) connection string — migrations require a persistent connection that the pooler can't provide. This is why the Prisma schema uses both url (pooled, for queries) and directUrl (direct, for migrations).

# .env.local
# For application queries (Server Components, API Routes, Server Actions)
DATABASE_URL="postgresql://USER:PASS@HOST-pooler.neon.tech/DBNAME?sslmode=require&pgbouncer=true"

# For Prisma migrate and introspect (direct connection only)
DATABASE_URL_UNPOOLED="postgresql://USER:PASS@HOST.neon.tech/DBNAME?sslmode=require"

Step 11: Deploy to Vercel

Vercel is the most popular deployment platform for Next.js and has a first-class Neon integration that makes it trivial to connect your database to your deployed application. Once connected, Vercel automatically injects the correct Neon environment variables into your deployment.

"scripts": {
  "build": "prisma migrate deploy && next build",
  "dev": "next dev",
  "start": "next start"
}

Advanced Query Patterns

Parameterized Queries and SQL Injection Safety

The Neon driver's tagged template literal syntax automatically parameterizes any JavaScript value you interpolate into a query. This makes it impossible to accidentally create a SQL injection vulnerability through interpolation — the driver always sends values as separate parameters, never concatenated into the query string.

// “& SAFE — driver parameterizes userInput automatically
const userId = req.params.id;
const rows = await sql`SELECT * FROM users WHERE id = ${userId}`;

// ’R NEVER DO THIS — string concatenation bypasses parameterization
const rows = await sql`SELECT * FROM users WHERE id = ` + userId; // SQL injection risk!

// “& SAFE — multiple parameters, all automatically escaped
const rows = await sql`
  SELECT * FROM posts
  WHERE author_id = ${authorId}
  AND published = ${true}
  AND created_at > ${startDate}
  LIMIT ${limit}
`;

Transactions

When you need to perform multiple related writes that must all succeed or all fail together — for example, creating an order and deducting inventory simultaneously — you need a database transaction. The Neon serverless driver supports transactions using the transaction method.

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

async function placeOrder(userId: number, productId: number, quantity: number) {
  const sql = neon(process.env.DATABASE_URL!);

  // All queries inside the array run in a single transaction
  const [order] = await sql.transaction([
    sql`
      INSERT INTO orders (user_id, product_id, quantity, created_at)
      VALUES (${userId}, ${productId}, ${quantity}, NOW())
      RETURNING id
    `,
    sql`
      UPDATE products
      SET stock = stock - ${quantity}
      WHERE id = ${productId} AND stock >= ${quantity}
    `,
  ]);

  return order;
}

Dynamic Filters with Conditional Queries

Building search and filter features often requires queries where the WHERE clause changes based on user input. The Neon driver lets you compose queries conditionally:

import { neon, sql as neonSql } from '@neondatabase/serverless';

async function searchPosts(filters: {
  authorId?: number;
  published?: boolean;
  searchTerm?: string;
}) {
  const sql = neon(process.env.DATABASE_URL!);

  const rows = await sql`
    SELECT id, title, body, created_at
    FROM posts
    WHERE TRUE
    ${filters.authorId ? neonSql`AND author_id = ${filters.authorId}` : neonSql``}
    ${filters.published !== undefined ? neonSql`AND published = ${filters.published}` : neonSql``}
    ${filters.searchTerm ? neonSql`AND title ILIKE ${'%' + filters.searchTerm + '%'}` : neonSql``}
    ORDER BY created_at DESC
  `;

  return rows;
}

Security Best Practices

Database security is not just about preventing SQL injection. Here is a full checklist of security practices to apply when connecting Next.js to Neon in production.

• Always use the sslmode=require parameter in your connection string to enforce encrypted connections to the database.
• Store all credentials in environment variables — never hardcode connection strings, passwords, or API keys in your source code.
• Use Neon's role management to create a read-only database role for queries that do not need to write, and a write role for mutation operations.
• Validate and sanitize all user input before it reaches your database layer, even when using parameterized queries. Validate types, lengths, and formats at the API boundary.
• Never expose raw database error messages to API clients. Log errors server-side with sufficient detail, but return generic error messages to the client.
• Use Neon's IP Allow List feature (available on paid plans) to restrict database access to your application server IP addresses only.
• Rotate database passwords periodically and immediately if you suspect a credential has been exposed.
• Audit your Neon project's access logs regularly for unexpected connection attempts or unusual query patterns.
• In Prisma, avoid using prisma.$executeRawUnsafe() with user-provided values — prefer parameterized raw queries with prisma.$executeRaw tagged templates.

Neon Branching for Dev and Staging

One of Neon's most powerful and distinctive features is database branching. Just like Git branches let you work on code changes in isolation without affecting the main codebase, Neon branches let you create isolated copies of your database for development, testing, or feature work — without duplicating the actual data storage.

Branches are copy-on-write, which means creating a branch is instant and nearly free regardless of database size. Changes you make on a branch do not affect the parent branch. When you are done, you can merge changes back or simply delete the branch.

Troubleshooting Common Issues

FAQ

Can I use the Neon driver on the Edge Runtime?

Yes. The @neondatabase/serverless driver is compatible with the Vercel Edge Runtime and Cloudflare Workers. Use the HTTP transport mode (the default when webSocketConstructor is not set) for edge environments. Edge compatibility makes it possible to run database queries at the CDN level for ultra-low latency global applications.

Is Neon compatible with all PostgreSQL features?

Neon runs standard PostgreSQL, so nearly all PostgreSQL features work as expected: full-text search, JSONB columns, window functions, CTEs, foreign keys, indexes, triggers, and extensions like pgvector for AI embeddings or uuid-ossp for UUID generation. The main limitation is that some PostgreSQL superuser features are restricted, which is typical of hosted database services.

How does Neon handle backups?

Neon automatically backs up your data continuously using write-ahead log (WAL) archiving. You can restore your database to any point in time within your retention window (7 days on the free tier, longer on paid plans) using the Neon dashboard's point-in-time restore feature. You can also use Neon's branching as an instant snapshot mechanism — create a branch before a risky migration to have a zero-downtime rollback option.

Can I import an existing PostgreSQL database into Neon?

Yes. Use pg_dump to export your existing database and psql or pg_restore to import it into Neon. Alternatively, use Neon's logical replication feature to migrate live data with minimal downtime from an existing PostgreSQL database.

What's the difference between using the raw Neon driver vs. Prisma?

The raw Neon driver is simpler and has less overhead — great for simple applications, scripts, or when you want full control over your SQL. Prisma adds type safety (auto-generated TypeScript types from your schema), a migration system, a query builder, and better tooling for complex data models. For production applications with complex schemas and multiple developers, Prisma's structure and type safety usually justify the added setup complexity. For quick prototypes or read-heavy dashboards with simple queries, the raw driver is faster to get started with.

Does Neon work with other Next.js ORMs like Drizzle?

Yes. Drizzle ORM has official support for Neon and is an increasingly popular alternative to Prisma in the Next.js ecosystem. Drizzle is lighter-weight, keeps SQL more explicit, and has excellent TypeScript inference. To use Drizzle with Neon, install drizzle-orm and drizzle-kit alongside @neondatabase/serverless and follow Drizzle's Neon integration guide in their documentation.