Back to Knowledge
Updated Sep 2026

Neon Playbook

Your app needs to remember things. This playbook covers the SQL vs. NoSQL

NoSQL

Databases that store data in a format other than relational tables, often as documents (JSON-like). Flexible and scalable.

"Like a folder of word documents. You can throw any kind of info into a doc; they don't all have to look the same."

question, then goes deep on Neon

Neon

Serverless PostgreSQL. It auto-scales, scales to zero when idle, branches like Git, and has a free tier (as of Sep 2026). You can provision it straight from the Vercel Marketplace. Perfect for vibe coding.

"Like PostgreSQL that wakes up when you need it and sleeps when you don't. Pay for what you use."

, our default Postgres

PostgreSQL

A powerful, open-source relational database. Rock-solid, feature-rich, and the choice for serious production apps.

"Like the Toyota Camry of databases. Reliable, well-documented, handles anything you throw at it."

 host: how to get it, how branching works, and how to avoid the classic pitfalls.

1The Big Picture

A database is where your app stores data: users, posts, orders, anything that must survive a restart. The right choice depends on your data's shape and how you query it.

The Two Big Categories

SQL (Relational)

Data lives in tables with rows and columns, like a strict spreadsheet. Relationships are enforced. Great for structured data.

PostgreSQL, MySQL, SQLite

NoSQL (Non-Relational)

Data stored as documents, key-value pairs, or graphs. Flexible shape. Great for loosely structured data.

MongoDB, Firestore, Redis, DynamoDB

2When Each Database Shines

PostgreSQL

The Swiss Army knife. Does almost everything well.

Best For

  • • Complex queries and joins
  • • Money, orders, anything transactional
  • • Apps with clear relationships
  • • When you need ACID guarantees

Example Use Cases

  • • E-commerce (orders, users, products)
  • • SaaS dashboards
  • • Almost any Next.js app
  • • CMS and admin panels

Vibe Coder Take: When in doubt, use Postgres. It handles the vast majority of apps and scales further than you think.

MongoDB

Document database. JSON-like storage.

Best For

  • • Rapidly changing shapes
  • • Deeply nested data
  • • Records with wildly different fields
  • • Event and log storage

Example Use Cases

  • • Product catalogs with varied attributes
  • • Content with many post types
  • • IoT data logging
  • • Analytics events

Vibe Coder Take: Pick it over Postgres only when your data truly doesn't fit tables. (Postgres JSONB columns cover a lot of this.)

Firebase / Firestore

Google's realtime document database with built-in auth.

Best For

  • • Realtime sync (chat, live updates)
  • • Mobile apps (iOS, Android, Flutter)
  • • Offline-first apps
  • • MVPs that want auth + DB in one SDK

Example Use Cases

  • • Chat apps
  • • Collaborative tools
  • • Mobile games with leaderboards
  • • Social apps

Vibe Coder Take: Pick it when realtime and offline are core features, or you're building mobile-first.

Redis

In-memory key-value store. Blazing fast, not your source of truth.

Best For

  • • Caching slow queries
  • • Session storage
  • • Rate limiting
  • • Leaderboards and counters

Example Use Cases

  • • API response caching
  • • Login sessions
  • • Per-user request limits
  • • Pub/sub messaging

Vibe Coder Take: Redis pairs with a primary database; it doesn't replace one. On Vercel, add Upstash Redis from the Marketplace.

SQLite

Embedded database. Lives in a single file.

Best For

  • • Local-first apps
  • • Electron and desktop apps
  • • Prototypes and scripts
  • • One small database per user

Example Use Cases

  • • Mobile apps with on-device storage
  • • CLI tools that need persistence
  • • Browser extensions
  • • Hosted SQLite via Turso or Cloudflare D1

Vibe Coder Take: Hosted SQLite services (Turso, Cloudflare D1) make it viable for web apps too, but it's a different SQL dialect from Postgres.

3Where Neon Fits In

Neon = Serverless Postgres

Neon gives you real PostgreSQL without managing a server. Think of it like a laptop that sleeps when you close the lid: compute switches off when nobody's querying and wakes up on the next request, while your data stays safely on disk. Other Postgres hosts include Supabase, PlanetScale, AWS RDS, and Google Cloud SQL.

Scale to Zero

Compute suspends after 5 minutes idle. The first query after a nap takes a moment longer.

Branching

Instant copy-on-write copies of your database, like Git branches for data.

Autoscaling

Compute grows with load (up to 2 CU on the free plan) and shrinks back.

Free plan (Sep 2026): 0.5 GB storage per project, 100 CU-hours per project, up to 100 projects, 10 branches. The paid entry plan, Launch, is usage-based. Current pricing ↗

When to Choose Neon

  • Next.js + Vercel projects: one-command Marketplace install and a database branch for preview deployments
  • Side projects and MVPs: a free plan that doesn't expire, and no servers to babysit
  • Safe experiments: branch the DB, try a risky migration, throw it away
  • Spiky or low traffic: you aren't paying for compute while it sleeps

4Getting Neon (Two Routes)

Route A: Vercel Marketplace

Billed through Vercel. Installs the integration, connects it to your linked project, and writes the credentials to .env.local. This replaced the old "Vercel Postgres".

Terminal

vercel link
vercel install neon

Route B: Neon account

Billed through Neon. Sign up at neon.com, or let the Neon CLI set up your project (it can also install the Neon plugin for Claude Code). Connect it to Vercel later as a "connectable account" if you like.

Terminal

npx neon@latest init

5Branching: A Database per Preview

Every pull request on Vercel gets a preview deployment

Preview Deployment

An automatic staging environment created for every pull request or branch. Lets you see and test changes before merging to production.

"Like a dress rehearsal before opening night. See exactly how it looks before going live."

. With the Neon integration, each preview can also get its own database branch: a copy of your data where that PR's migrations

Migration

A controlled change to your database schema. Lets you version-control your database structure and safely update it.

"Like renovating a house room by room, with blueprints for each change."

 run without touching production. Merge the PR, and production gets the migration for real.

main

Production data. Only merged migrations land here.

preview/feature-x

Auto-created for a preview deployment. Safe to break.

dev

Your personal sandbox for local development.

Terminal: make a dev branch by hand

npx neon@latest branches create --name dev
npx neon@latest branches list

Watch the branch count. The free plan allows 10 branches. With the Vercel-managed integration, preview branches are cleaned up based on Vercel's deployment retention, which can take a long time. With a Neon-managed integration, deleting the Git branch cleans them up. Prune old ones in the Neon console if you hit the limit.

6Neon vs Supabase vs PlanetScale

All three now offer Postgres. The difference is what comes with it, and what it costs to start.

Neon

Free plan

Just Postgres, done well: serverless, branching, scale-to-zero.

Best for: Vercel projects, side projects, anyone who wants branch-per-preview.

Supabase

Free plan

Postgres plus Auth, Storage, Realtime, and Supabase Edge Functions. All-in-one backend.

Best for: Apps that want auth and file storage from the same vendor. Free projects pause after a week of inactivity.

PlanetScale

Paid only

Managed Postgres and MySQL (Vitess) built for high-stakes production. No free tier.

Best for: Funded production apps, teams that already run MySQL/Vitess, large-scale workloads.

Our Take: Just need a database → Neon. Want auth + DB + storage in one → Supabase. Paying customers and a budget for managed HA → PlanetScale is worth a look. Full comparison in Choosing Your Database.

7Framework Pairings

Different frameworks have natural database partners:

Next.js
Neon or Supabase

Both install from the Vercel Marketplace

React Native
Firebase or Supabase

Realtime sync, offline support, built-in auth

Flutter
Firebase

Native Dart SDK, realtime listeners

Remix / Nuxt
Neon + Drizzle

Server-rendered apps love Postgres

FastAPI / Django
Neon or any Postgres

See the Python stack guide for drivers

Electron
SQLite

Embedded, no server needed, ships with your app

8Common Pitfalls (And How to Avoid Them)

Picking NoSQL because “it's easier”

MongoDB feels easy at first. No schema! But as the app grows you'll miss joins and constraints. Most apps have relational data.

Fix: Start with Postgres. An ORM like Drizzle makes it feel like working with objects, and your AI assistant writes most of the SQL anyway.

Using the production database for development

One wrong DELETE and real users are affected. Testing migrations on production is how outages happen.

Fix: Create a Neon branch for dev work. It's a full copy of production data that you can wreck and reset in seconds.

Forgetting about connection limits

Serverless functions run many copies at once. If each one opens its own Postgres connection, you run out.

Fix: Use the pooled connection string (the hostname contains -pooler) for your app, or the HTTP driver. Use the direct (unpooled) string for migrations and pg_dump.

Pointing an AI agent's MCP server at production

MCP lets Claude Code run SQL for you. That's amazing on a dev branch and terrifying on prod.

Fix: Neon's own docs recommend MCP for development and testing only. Approve every write it proposes.

Committing DATABASE_URL

Connection strings contain the password. Once it's in Git history, assume it's leaked.

Fix: Keep it in .env.local (gitignored) and in Vercel env vars. Use different credentials or branches for dev and prod. Rotate if it leaks.

9Neon + Claude Code

Neon runs an official remote MCP

MCP (Model Context Protocol)

An open standard for connecting AI apps to external tools and data (databases, GitHub, docs, browsers). Servers run locally over stdio or remotely over Streamable HTTP, and remote servers use OAuth 2.1 for sign-in. In Claude Code: `claude mcp add --transport http <name> <url>`.

"Like USB ports for AI. A universal way to plug in new capabilities."

server. Connect it and Claude Code

Claude Code

Anthropic's agentic coding tool. It lives in your terminal (and in VS Code, JetBrains, and on the web), reads your codebase, edits files, runs commands, and ships code. Install with the native installer (`curl -fsSL https://claude.ai/install.sh | bash` on macOS/Linux, `irm https://claude.ai/install.ps1 | iex` on Windows); it needs a Pro, Max, Team, Enterprise, or Console account.

"Like having a senior developer living in your terminal, ready to help 24/7."

 can list tables, run queries, and create branches for you. The easiest path is the Neon CLI (it installs the Neon plugin for supported agents); you can also add the server by hand.

Terminal

# Guided setup (Neon plugin for Claude Code and other agents)
npx neon@latest plugins

# Or add the remote MCP server manually
claude mcp add --transport http neon https://mcp.neon.tech/mcp

Then run /mcp in a session to sign in. More in the MCP guide. And remember: dev branches only.

10Quick Setup: Neon + Drizzle

The Vibe Coding Stack

Neon + Drizzle

Drizzle ORM

A lightweight, type-safe ORM for TypeScript. Your schema IS your types — no code generation, no sync issues. SQL-like syntax that feels natural.

"Like having a personal translator who speaks both TypeScript and SQL fluently. Zero confusion."

is our recommended combo: type-safe queries, generated migrations, and a driver built for serverless. The full walkthrough lives in Connect a Database.

1. Install packages

npm install drizzle-orm @neondatabase/serverless
npm install -D drizzle-kit

2. .env.local (vercel install neon writes this for you)

DATABASE_URL="postgresql://user:pass@ep-xxx-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require"

3. src/db/schema.ts

import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: serial("id").primaryKey(),
  email: text("email").unique().notNull(),
  name: text("name"),
  createdAt: timestamp("created_at").defaultNow(),
});

4. src/db/index.ts

import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle({ client: sql });

5. Push the schema to your dev branch

npx drizzle-kit push

Ready to build?

Spin up a free Neon database, connect it, and design your first tables.

Start on Neon Design Your Schema