Neon Postgres

Neon is a serverless PostgreSQL platform that offers connection pooling, database branching, autoscaling, and a generous free tier. It is a great choice for serverless deployments and modern SaaS applications.

This guide walks you through setting up Neon as your database provider for supastarter.

1. Create a Neon account and project

Go to neon.tech and create an account. Once signed in, create a new project. Choose the region closest to your deployment target for the best latency.

2. Get your connection strings

Neon provides two types of connection strings:

• Pooled connection string (uses PgBouncer): Used by your application at runtime for efficient connection management.
• Direct connection string: Used for database migrations, which require a persistent connection.

You can find both connection strings in the Neon dashboard under your project's Connection Details section.

The pooled connection string uses a -pooler suffix in the hostname:

postgresql://user:password@ep-xxx-pooler.region.aws.neon.tech/neondb?sslmode=require

The direct connection string connects directly to the database:

postgresql://user:password@ep-xxx.region.aws.neon.tech/neondb?sslmode=require

3. Configure environment variables

Add both connection strings to your .env.local file in the root of your project:

DATABASE_URL="postgresql://user:password@ep-xxx-pooler.region.aws.neon.tech/neondb?sslmode=require"
DIRECT_URL="postgresql://user:password@ep-xxx.region.aws.neon.tech/neondb?sslmode=require"

DATABASE_URL is the pooled connection string used by your application at runtime. DIRECT_URL is the direct connection string used for running migrations.

4. Configure your ORM

Prisma

If you are using Prisma, you need to configure it to use the direct connection string for migrations. Create or update the prisma.config.ts file in your packages/database directory:

import 'dotenv/config';
import { defineConfig, env } from 'prisma/config';

export default defineConfig({
  schema: './prisma/schema.prisma',
  datasource: {
    url: env('DIRECT_URL'),
  },
});

At runtime, Prisma Client automatically uses the DATABASE_URL environment variable (the pooled connection string) for all queries.

Drizzle

If you are using Drizzle, no special configuration is needed. The standard PostgreSQL setup works out of the box. Just make sure your DATABASE_URL is set to the pooled connection string.

5. Run migrations

Push your database schema to Neon:

pnpm --filter database push

6. Start the development server

Start your development server to verify everything is working:

pnpm dev

Frequently asked questions

Does Neon support connection pooling?

Yes, Neon includes built-in connection pooling via PgBouncer. Use the pooled endpoint (with -pooler in the hostname) for your application and the direct endpoint for migrations.

What are Neon's free tier limits?

Neon's free tier includes 0.5 GB of storage, 1 project, and 10 branches. This is generous enough for development and small production applications.

Can I use Neon with Drizzle?

Yes, Neon works with both Prisma and Drizzle. Use the standard PostgreSQL driver configuration with your pooled connection string as the DATABASE_URL.