Neon API

Neon provides serverless PostgreSQL with instant branching, autoscaling, and scale-to-zero. Two interfaces: the management REST API (projects, branches, operations) and the PostgreSQL wire protocol (your app’s database connection).

Management API

# List projects
curl -H "Authorization: Bearer $NEON_API_KEY" \
  https://console.neon.tech/api/v2/projects

# Create a branch
curl -X POST \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch": {"name": "feature-x"}}' \
  https://console.neon.tech/api/v2/projects/{project_id}/branches

Connecting with Psycopg (Python)

import psycopg
from psycopg.rows import dict_row

conninfo = {
    "host": "ep-xxxx-xxxx.us-east-2.aws.neon.tech",
    "dbname": "neondb",
    "user": "app_role",
    "password": "secret",
    "sslmode": "verify-full",
    "sslrootcert": "/etc/ssl/certs/ca-certificates.crt",
    "channel_binding": "require",
}

with psycopg.connect(**conninfo, row_factory=dict_row) as conn:
    conn.read_only = True  # for read-only queries
    with conn.cursor() as cur:
        cur.execute("SELECT count(*) AS count FROM projects")
        print(cur.fetchone()["count"])

Always use parameterized queries — never interpolate user input into SQL:

cur.execute("SELECT id FROM projects WHERE id = %s", (project_id,))

Key endpoints

Endpoint	Description
POST /v2/projects	Create project
GET /v2/projects	List projects
GET /v2/projects/{project_id}	Project details
DELETE /v2/projects/{project_id}	Delete project
POST /v2/projects/{project_id}/branches	Create branch
GET /v2/projects/{project_id}/branches	List branches
POST /v2/projects/{project_id}/endpoints	Create endpoint
GET /v2/projects/{project_id}/connection_uri	Connection string

Real-world notes

Direct vs pooled. Neon offers direct connections and a connection pooler. They behave differently for prepared statements, transactions, and migrations. Use direct connections for pg_dump/pg_restore and migrations; test the pooler separately before switching.

Cold starts. Suspended computes resume on first query, adding latency. Design health checks to distinguish “database warming up” from “database down.”

Branching. Branches are copy-on-write and instant. Ideal for per-PR databases or testing migrations safely.