Getting started with Neon

A database is an organized collection of data that your application can create, read, update, and delete. Think of it as a set of spreadsheets — each table has rows (records) and columns (fields).

Almost every application you use relies on a database behind the scenes:

When you build a web application, the database is where all the important information lives. The frontend (what users see) talks to a backend (server) that reads and writes to the database.

Traditionally, running a database meant setting up a server, installing database software, managing backups, and handling security patches. Cloud databases remove all of that:

• •No server to manage — the provider handles infrastructure, backups, and updates
• •Accessible from anywhere — connect from your local machine, a server, or an edge function
• •Scales automatically — handles traffic spikes without manual intervention
• •Free tiers — most providers offer generous free plans perfect for learning and side projects

Neon and Supabase are two popular cloud database platforms. Both use PostgreSQL under the hood, but each adds unique features on top.

Neon is a serverless PostgreSQL platform that separates storage and compute. This architecture enables unique features like instant branching, autoscaling, and scale-to-zero — meaning you only pay for the compute you actually use.

Because Neon focuses purely on being the best PostgreSQL database, it's a great choice when you want a powerful, standards-compliant database with modern cloud-native features.

Let's create your first Neon project:

1. Go to console.neon.tech
2. Sign up with GitHub (recommended), Google, or email.
3. Click "New Project," choose a project name and a region close to you.
4. Neon will create your project and show you a connection string.

Your connection string looks like this:

postgresql://username:password@ep-cool-name-123456.us-east-2.aws.neon.tech/neondb?sslmode=require

Before creating any tables, take a moment to think about your data model. A data model defines what information your app will store and how the pieces relate to each other.

This is arguably the most important step in building any application. A well-designed data model makes everything easier — queries are simpler, performance is better, and adding new features is straightforward.

Here's an example: imagine you're building an online store. You need products and orders:

Example: e‑commerce data model

Here's how you might define the tables in SQL:

-- Create a table for products
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT,
  price_cents INTEGER NOT NULL,
  in_stock BOOLEAN DEFAULT true,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Create a table for orders
CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  customer_email TEXT NOT NULL,
  product_id INTEGER REFERENCES products(id),
  quantity INTEGER DEFAULT 1,
  created_at TIMESTAMPTZ DEFAULT now()
);

Tips for designing your data model:

• •Choose appropriate primary key types — SERIAL for simple auto-incrementing IDs, UUID for distributed systems
• •Always add a created_at timestamp — you'll need it for sorting and debugging
• •Use foreign keys (REFERENCES) to connect related tables
• •Add sensible default values (DEFAULT true, DEFAULT now()) to reduce the data you need to send with every insert

Now let's create a real table using the Neon SQL Editor. We'll start with a simple todos table:

1. Open your project in the Neon console.
2. Go to the SQL Editor and paste the following SQL:

CREATE TABLE todos (
  id SERIAL PRIMARY KEY,
  task TEXT NOT NULL,
  is_complete BOOLEAN DEFAULT false,
  created_at TIMESTAMPTZ DEFAULT now()
);

Now add some test data and verify it:

INSERT INTO todos (task) VALUES ('Learn Neon');
INSERT INTO todos (task) VALUES ('Build my first app');
INSERT INTO todos (task, is_complete) VALUES ('Create an account', true);

SELECT * FROM todos;

Now let's connect to your Neon database from an actual application. Here's how to do it in both Node.js and Python:

🟢 Node.js

Install the Neon serverless driver:

npm install @neondatabase/serverless

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

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

// Fetch all todos
const todos = await sql`SELECT * FROM todos`;
console.log(todos);

// Insert a new todo
await sql`INSERT INTO todos (task) VALUES (${'Deploy to Vercel'})`;

// Update a todo
await sql`UPDATE todos SET is_complete = true WHERE id = ${1}`;

// Delete a todo
await sql`DELETE FROM todos WHERE id = ${1}`;

🐍 Python

Install the PostgreSQL adapter:

pip install psycopg2-binary

import psycopg2
import os

conn = psycopg2.connect(os.environ['DATABASE_URL'])
cur = conn.cursor()

cur.execute("SELECT * FROM todos")
rows = cur.fetchall()
print(rows)

cur.close()
conn.close()

Neon's standout feature is database branching. Just like Git lets you create branches of your code, Neon lets you create branches of your entire database — including all data and schema.

Branches are instant, copy-on-write snapshots. They don't duplicate storage, so they're lightweight and free to create. Here are some use cases:

• •Testing — create a branch to test a migration before running it on production
• •Development — give each developer their own database branch with real data
• •Previews — pair a Neon branch with a Vercel preview deployment for full-stack previews

You can create branches from the Neon console, the CLI, or the API. Each branch gets its own connection string.

Beyond the core database, Neon offers several features designed for modern cloud applications: