neon-postgres

name

neon-postgres

description

Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Neon's Platform API/SDKs. In the gangof4 repo, use the practiced workflow (go4 generate + neon target, push-to-neon script, Drizzle). Use for any Neon-related questions.

Neon Serverless Postgres

Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres.

When Working in the GangOf4 Repo

Use the practiced workflow so answers match how this codebase actually uses Neon:

Need	Resource
How we generate Neon config, push schema, choose HTTP vs WebSocket	references/gangof4-neon-workflow.md
Full generated files, options, push script, package deps	GangOf4 SDK skill → references/neon.md

In short: go4 migrate (or generate()) with target neon produces db/neon.ts, drizzle.config.ts, etc. Set DATABASE_URL in .env and run npx tsx scripts/push-to-neon.ts to push the generated Drizzle schema to Neon. Prefer the HTTP driver (default) for serverless; use --neon-websocket only for long-lived Node servers.

Neon Documentation

Always reference the Neon documentation before making Neon-related claims. The documentation is the source of truth for all Neon-related information.

Below you'll find a list of resources organized by area of concern. This is meant to support you find the right documentation pages to fetch and add a bit of additional context.

You can use the curl commands to fetch the documentation page as markdown:

Documentation:

# Get list of all Neon docs
curl https://neon.com/llms.txt

# Fetch any doc page as markdown
curl -H "Accept: text/markdown" https://neon.com/docs/<path>

Don't guess docs pages. Use the llms.txt index to find the relevant URL or follow the links in the resources below.

Overview of Resources

Reference the appropriate resource file based on the user's needs:

This Workspace (GangOf4)

Area	Resource	When to Use
GangOf4 Neon workflow	references/gangof4-neon-workflow.md	How this repo uses Neon: go4 generate + neon target, push script, DATABASE_URL

Core Guides

Area	Resource	When to Use
What is Neon	references/what-is-neon.md	Understanding Neon concepts, architecture, core resources
Referencing Docs	references/referencing-docs.md	Looking up official documentation, verifying information
Features	references/features.md	Branching, autoscaling, scale-to-zero, instant restore
Getting Started	references/getting-started.md	Setting up a project, connection strings, dependencies, schema
Connection Methods	references/connection-methods.md	Choosing drivers based on platform and runtime
Developer Tools	references/devtools.md	VSCode extension, MCP server, Neon CLI (neon init)

Database Drivers & ORMs

HTTP/WebSocket queries for serverless/edge functions.

Area	Resource	When to Use
Serverless Driver	references/neon-serverless.md	@neondatabase/serverless - HTTP/WebSocket queries
Drizzle ORM	references/neon-drizzle.md	Drizzle ORM integration with Neon

Auth & Data API SDKs

Authentication and PostgREST-style data API for Neon.

Area	Resource	When to Use
Neon Auth	references/neon-auth.md	@neondatabase/auth - Authentication only
Neon JS SDK	references/neon-js.md	@neondatabase/neon-js - Auth + Data API (PostgREST-style queries)

Neon Platform API & CLI

Managing Neon resources programmatically via REST API, SDKs, or CLI.

Area	Resource	When to Use
Platform API Overview	references/neon-platform-api.md	Managing Neon resources via REST API
Neon CLI	references/neon-cli.md	Terminal workflows, scripts, CI/CD pipelines
TypeScript SDK	references/neon-typescript-sdk.md	@neondatabase/api-client
Python SDK	references/neon-python-sdk.md	neon-api package