Neon Postgres

1---
2name: neon-postgres
3description: 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. Use for any Neon-related questions.
4---
5 
6# Neon Serverless Postgres
7 
8Neon 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.
9 
10## Neon Documentation
11 
12The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data.
13 
14### Fetching Docs as Markdown
15 
16Any Neon doc page can be fetched as markdown in two ways:
17 
181. **Append `.md` to the URL** (simplest): `https://neon.com/docs/introduction/branching.md`
192. **Request `text/markdown`** on the standard URL: `curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching`
20 
21Both return the same markdown content. Use whichever method your tools support.
22 
23### Finding the Right Page
24 
25The docs index lists every available page with its URL and a short description:
26 
27```
28https://neon.com/docs/llms.txt
29```
30 
31Common doc URLs are organized in the topic links below. If you need a page not listed here, search the [docs index](https://neon.com/docs/llms.txt) — don't guess URLs.
32 
33## What Is Neon
34 
35Use this for architecture explanations and terminology (organizations, projects, branches, endpoints) before giving implementation advice.
36 
37Link: `references/what-is-neon.md`
38 
39## Getting Started
40 
41Use this for first-time setup: org/project selection, connection strings, driver installation, optional auth, and initial schema setup.
42 
43Link: `references/getting-started.md`
44 
45## Connection Methods & Drivers
46 
47Use this when you need to pick the correct transport and driver based on runtime constraints (TCP, HTTP, WebSocket, edge, serverless, long-running).
48 
49Link: `references/connection-methods.md`
50 
51### Serverless Driver
52 
53Use this for `@neondatabase/serverless` patterns, including HTTP queries, WebSocket transactions, and runtime-specific optimizations.
54 
55Link: `references/neon-serverless.md`
56 
57### Neon JS SDK
58 
59Use this for combined Neon Auth + Data API workflows with PostgREST-style querying and typed client setup.
60 
61Link: `references/neon-js.md`
62 
63## Developer Tools
64 
65Use this for local development enablement with `npx neonctl@latest init`, VSCode extension setup, and Neon MCP server configuration.
66 
67Link: `references/devtools.md`
68 
69### Neon CLI
70 
71Use this for terminal-first workflows, scripts, and CI/CD automation with `neonctl`.
72 
73Link: `references/neon-cli.md`
74 
75## Neon Admin API
76 
77The Neon Admin API can be used to manage Neon resources programmatically. It is used behind the scenes by the Neon CLI and MCP server, but can also be used directly for more complex automation workflows or when embedding Neon in other applications.
78 
79### Neon REST API
80 
81Use this for direct HTTP automation, endpoint-level control, API key auth, rate-limit handling, and operation polling.
82 
83Link: `references/neon-rest-api.md`
84 
85### Neon TypeScript SDK
86 
87Use this when implementing typed programmatic control of Neon resources in TypeScript via `@neondatabase/api-client`.
88 
89Link: `references/neon-typescript-sdk.md`
90 
91### Neon Python SDK
92 
93Use this when implementing programmatic Neon management in Python with the `neon-api` package.
94 
95Link: `references/neon-python-sdk.md`
96 
97## Neon Auth
98 
99Use this for managed user authentication setup, UI components, auth methods, and Neon Auth integration pitfalls in Next.js and React apps.
100 
101Link: `references/neon-auth.md`
102 
103Neon Auth is also embedded in the Neon JS SDK - so depending on your use case, you may want to use the Neon JS SDK instead of Neon Auth. See `references/connection-methods.md` for more details.
104 
105## Branching
106 
107Use this when the user is planning isolated environments, schema migration testing, preview deployments, or branch lifecycle automation.
108 
109Key points:
110 
111- Branches are instant, copy-on-write clones (no full data copy).
112- Each branch has its own compute endpoint.
113- Use the neonctl CLI or MCP server to create, inspect, and compare branches.
114 
115Link: `references/branching.md`
116 
117## Autoscaling
118 
119Use this when the user needs compute to scale automatically with workload and wants guidance on CU sizing and runtime behavior.
120 
121Link: https://neon.com/docs/introduction/autoscaling.md
122 
123## Scale to Zero
124 
125Use this when optimizing idle costs and discussing suspend/resume behavior, including cold-start trade-offs.
126 
127Key points:
128 
129- Idle computes suspend automatically (default 5 minutes, configurable) (unless disabled - launch & scale plan only)
130- First query after suspend typically has a cold-start penalty (around hundreds of ms)
131- Storage remains active while compute is suspended.
132 
133Link: https://neon.com/docs/introduction/scale-to-zero.md
134 
135## Instant Restore
136 
137Use this when the user needs point-in-time recovery or wants to restore data state without traditional backup restore workflows.
138 
139Key points:
140 
141- Restore windows depend on plan limits.
142- Users can create branches from historical points-in-time.
143- Time Travel queries can be used for historical inspection workflows.
144 
145Link: https://neon.com/docs/introduction/branch-restore.md
146 
147## Read Replicas
148 
149Use this for read-heavy workloads where the user needs dedicated read-only compute without duplicating storage.
150 
151Key points:
152 
153- Replicas are read-only compute endpoints sharing the same storage.
154- Creation is fast and scaling is independent from primary compute.
155- Typical use cases: analytics, reporting, and read-heavy APIs.
156 
157Link: https://neon.com/docs/introduction/read-replicas.md
158 
159## Connection Pooling
160 
161Use this when the user is in serverless or high-concurrency environments and needs safe, scalable Postgres connection management.
162 
163Key points:
164 
165- Neon pooling uses PgBouncer.
166- Add `-pooler` to endpoint hostnames to use pooled connections.
167- Pooling is especially important in serverless runtimes with bursty concurrency.
168 
169Link: https://neon.com/docs/connect/connection-pooling.md
170 
171## IP Allow Lists
172 
173Use this when the user needs to restrict database access by trusted networks, IPs, or CIDR ranges.
174 
175Link: https://neon.com/docs/introduction/ip-allow.md
176 
177## Logical Replication
178 
179Use this when integrating CDC pipelines, external Postgres sync, or replication-based data movement.
180 
181Key points:
182 
183- Neon supports native logical replication workflows.
184- Useful for replicating to/from external Postgres systems.
185 
186Link: https://neon.com/docs/guides/logical-replication-guide.md
187