This commit is contained in:
admin
8
neon-postgres/.skillshare-meta.json
Normal file
8
neon-postgres/.skillshare-meta.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"source": "github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres",
|
||||
"type": "github-subdir",
|
||||
"installed_at": "2026-01-30T02:26:42.558902032Z",
|
||||
"repo_url": "https://github.com/neondatabase/agent-skills.git",
|
||||
"subdir": "skills/neon-postgres",
|
||||
"version": "758ac1a"
|
||||
}
|
||||
72
neon-postgres/SKILL.md
Normal file
72
neon-postgres/SKILL.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
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. 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.
|
||||
|
||||
## 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 additonal context.
|
||||
|
||||
You can use the `curl` commands to fetch the documentation page as markdown:
|
||||
|
||||
**Documentation:**
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
### 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 |
|
||||
193
neon-postgres/references/connection-methods.md
Normal file
193
neon-postgres/references/connection-methods.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Connection Methods
|
||||
|
||||
Guide to selecting the optimal connection method for your Neon Postgres database based on deployment platform and runtime environment.
|
||||
|
||||
For official documentation:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/connect/choose-connection
|
||||
```
|
||||
|
||||
## Decision Tree
|
||||
|
||||
Follow this flow to determine the right connection approach:
|
||||
|
||||
### 1. What Language Are You Using?
|
||||
|
||||
**Not TypeScript/JavaScript** → Use **TCP with connection pooling** from a secure server.
|
||||
|
||||
For non-TypeScript languages, connect from a secure backend server using your language's native Postgres driver with connection pooling enabled.
|
||||
|
||||
| Language/Framework | Documentation |
|
||||
| ------------------- | ------------------------------------------- |
|
||||
| Django (Python) | https://neon.com/docs/guides/django |
|
||||
| SQLAlchemy (Python) | https://neon.com/docs/guides/sqlalchemy |
|
||||
| Elixir Ecto | https://neon.com/docs/guides/elixir-ecto |
|
||||
| Laravel (PHP) | https://neon.com/docs/guides/laravel |
|
||||
| Ruby on Rails | https://neon.com/docs/guides/ruby-on-rails |
|
||||
| Go | https://neon.com/docs/guides/go |
|
||||
| Rust | https://neon.com/docs/guides/rust |
|
||||
| Java | https://neon.com/docs/guides/java |
|
||||
|
||||
**TypeScript/JavaScript** → Continue to step 2.
|
||||
|
||||
---
|
||||
|
||||
### 2. Client-Side App Without Backend?
|
||||
|
||||
**Yes** → Use **Neon Data API** via `@neondatabase/neon-js`
|
||||
|
||||
This is the only option for client-side apps since browsers cannot make direct TCP connections to Postgres. See `neon-js.md` for setup.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/javascript-sdk
|
||||
```
|
||||
|
||||
**No** → Continue to step 3.
|
||||
|
||||
---
|
||||
|
||||
### 3. Long-Running Server? (Railway, Render, traditional VPS)
|
||||
|
||||
**Yes** → Use **TCP with connection pooling** via `node-postgres`, `postgres.js`, or `bun:pg`
|
||||
|
||||
Long-running servers maintain persistent connections, so standard TCP drivers with pooling are optimal.
|
||||
|
||||
**No** → Continue to step 4.
|
||||
|
||||
---
|
||||
|
||||
### 4. Edge Environment Without TCP Support?
|
||||
|
||||
Some edge runtimes don't support TCP connections. Rarely the case anymore.
|
||||
|
||||
**Yes** → Continue to step 5 to check transaction requirements.
|
||||
|
||||
**No** → Continue to step 6 to check pooling support.
|
||||
|
||||
---
|
||||
|
||||
### 5. Does Your App Use SQL Transactions?
|
||||
|
||||
**Yes** → Use **WebSocket transport** via `@neondatabase/serverless` with `Pool`
|
||||
|
||||
WebSocket maintains connection state needed for transactions. See `neon-serverless.md` for setup.
|
||||
|
||||
**No** → Use **HTTP transport** via `@neondatabase/serverless`
|
||||
|
||||
HTTP is faster for single queries (~3 roundtrips vs ~8 for TCP). See `neon-serverless.md` for setup.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/serverless/serverless-driver
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Serverless Environment With Connection Pooling Support?
|
||||
|
||||
**Vercel (Fluid Compute)** → Use **TCP with `@vercel/functions`**
|
||||
|
||||
Vercel's Fluid compute supports connection pooling. Use `attachDatabasePool` for optimal connection management.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/guides/vercel-connection-methods
|
||||
```
|
||||
|
||||
**Cloudflare (with Hyperdrive)** → Use **TCP via Hyperdrive**
|
||||
|
||||
Cloudflare Hyperdrive provides connection pooling for Workers. Use `node-postgres` or any native TCP driver.
|
||||
|
||||
See https://neon.com/docs/guides/cloudflare-hyperdrive for more on connecting with Cloudflare Workers and Hyperdrive.
|
||||
|
||||
**No pooling support (Netlify, Deno Deploy)** → Use `@neondatabase/serverless`
|
||||
|
||||
Fall back to the decision in step 5 based on transaction requirements.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Table
|
||||
|
||||
| Platform | TCP Support | Pooling | Recommended Driver |
|
||||
| ----------------------- | ----------- | ------------------- | -------------------------- |
|
||||
| Vercel (Fluid) | Yes | `@vercel/functions` | `pg` (node-postgres) |
|
||||
| Cloudflare (Hyperdrive) | Yes | Hyperdrive | `pg` (node-postgres) |
|
||||
| Cloudflare Workers | No | No | `@neondatabase/serverless` |
|
||||
| Netlify Functions | No | No | `@neondatabase/serverless` |
|
||||
| Deno Deploy | No | No | `@neondatabase/serverless` |
|
||||
| Railway / Render | Yes | Built-in | `pg` (node-postgres) |
|
||||
| Client-side (browser) | No | N/A | `@neondatabase/neon-js` |
|
||||
|
||||
---
|
||||
|
||||
## ORM Support
|
||||
|
||||
Popular TypeScript/JavaScript ORMs all work with Neon:
|
||||
|
||||
| ORM | Drivers Supported | Documentation |
|
||||
| ------- | ----------------------------------------------- | ------------------------------------- |
|
||||
| Drizzle | `pg`, `postgres.js`, `@neondatabase/serverless` | https://neon.com/docs/guides/drizzle |
|
||||
| Kysely | `pg`, `postgres.js`, `@neondatabase/serverless` | https://neon.com/docs/guides/kysely |
|
||||
| Prisma | `pg`, `@neondatabase/serverless` | https://neon.com/docs/guides/prisma |
|
||||
| TypeORM | `pg` | https://neon.com/docs/guides/typeorm |
|
||||
|
||||
All ORMs support both TCP drivers and Neon's serverless driver depending on your platform.
|
||||
|
||||
For Drizzle ORM integration with Neon, see `neon-drizzle.md`.
|
||||
|
||||
---
|
||||
|
||||
## Vercel Fluid + Drizzle Example
|
||||
|
||||
Complete database client setup for Vercel with Drizzle ORM and connection pooling. See `neon-drizzle.md` for more examples.
|
||||
|
||||
```typescript
|
||||
// src/lib/db/client.ts
|
||||
import { attachDatabasePool } from "@vercel/functions";
|
||||
import { drizzle } from "drizzle-orm/node-postgres";
|
||||
import { Pool } from "pg";
|
||||
|
||||
import * as schema from "./schema";
|
||||
|
||||
const pool = new Pool({
|
||||
connectionString: process.env.DATABASE_URL,
|
||||
});
|
||||
attachDatabasePool(pool);
|
||||
|
||||
export const db = drizzle({ client: pool, schema });
|
||||
```
|
||||
|
||||
**Why `attachDatabasePool`?**
|
||||
|
||||
- First request establishes the TCP connection (~8 roundtrips)
|
||||
- Subsequent requests reuse the connection instantly
|
||||
- Ensures idle connections close gracefully before function suspension
|
||||
- Prevents connection leaks in serverless environments
|
||||
|
||||
---
|
||||
|
||||
## Gathering Requirements
|
||||
|
||||
When helping a user choose their connection method, gather this information:
|
||||
|
||||
1. **Deployment platform**: Where will the app run? (Vercel, Cloudflare, Netlify, Railway, browser, etc.)
|
||||
2. **Runtime type**: Serverless functions, edge functions, or long-running server?
|
||||
3. **Transaction requirements**: Does the app need SQL transactions?
|
||||
4. **ORM preference**: Using Drizzle, Kysely, Prisma, or raw SQL?
|
||||
|
||||
Then provide:
|
||||
|
||||
- The recommended driver/package
|
||||
- A working code example for their setup
|
||||
- The correct npm install command
|
||||
|
||||
---
|
||||
|
||||
## Documentation Resources
|
||||
|
||||
| Topic | URL |
|
||||
| -------------------------- | ------------------------------------------------------- |
|
||||
| Choosing Connection Method | https://neon.com/docs/connect/choose-connection |
|
||||
| Serverless Driver | https://neon.com/docs/serverless/serverless-driver |
|
||||
| JavaScript SDK | https://neon.com/docs/reference/javascript-sdk |
|
||||
| Connection Pooling | https://neon.com/docs/connect/connection-pooling |
|
||||
| Vercel Connection Methods | https://neon.com/docs/guides/vercel-connection-methods |
|
||||
121
neon-postgres/references/devtools.md
Normal file
121
neon-postgres/references/devtools.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# Neon Developer Tools
|
||||
|
||||
Neon provides developer tools to enhance your local development workflow, including a VSCode extension and MCP server for AI-assisted development.
|
||||
|
||||
## Quick Setup with neon init
|
||||
|
||||
The fastest way to set up all Neon developer tools:
|
||||
|
||||
```bash
|
||||
npx neon init
|
||||
```
|
||||
|
||||
This command:
|
||||
|
||||
- Installs the Neon VSCode extension
|
||||
- Configures the Neon MCP server for AI assistants
|
||||
- Sets up your local environment for Neon development
|
||||
|
||||
For full CLI reference:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/cli-init
|
||||
```
|
||||
|
||||
## VSCode Extension
|
||||
|
||||
The Neon VSCode extension provides:
|
||||
|
||||
- **Database Explorer**: Browse projects, branches, tables, and data
|
||||
- **SQL Editor**: Write and execute queries with IntelliSense
|
||||
- **Branch Management**: Create, switch, and manage database branches
|
||||
- **Connection String Access**: Quick copy of connection strings
|
||||
|
||||
**Install from VSCode:**
|
||||
|
||||
1. Open Extensions (Cmd/Ctrl+Shift+X)
|
||||
2. Search "Neon"
|
||||
3. Install "Neon" by Neon
|
||||
|
||||
**Or via command line:**
|
||||
|
||||
```bash
|
||||
code --install-extension neon.neon-vscode
|
||||
```
|
||||
|
||||
For detailed documentation:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/local/vscode-extension
|
||||
```
|
||||
|
||||
## Neon MCP Server
|
||||
|
||||
The Neon MCP (Model Context Protocol) server enables AI assistants like Claude, Cursor, and GitHub Copilot to interact with your Neon databases directly.
|
||||
|
||||
### Capabilities
|
||||
|
||||
The MCP server provides AI assistants with:
|
||||
|
||||
- **Project Management**: List, create, describe, and delete projects
|
||||
- **Branch Operations**: Create branches, compare schemas, reset from parent
|
||||
- **SQL Execution**: Run queries and transactions
|
||||
- **Schema Operations**: Describe tables, get database structure
|
||||
- **Migrations**: Prepare and complete database migrations with safety checks
|
||||
- **Query Tuning**: Analyze and optimize slow queries
|
||||
- **Neon Auth**: Provision authentication for your branches
|
||||
|
||||
### Setup
|
||||
|
||||
**Option 1: Via neon init (Recommended)**
|
||||
|
||||
```bash
|
||||
npx neon init
|
||||
```
|
||||
|
||||
**Option 2: Manual Configuration**
|
||||
|
||||
Add to your AI assistant's MCP configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"neon": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@neondatabase/mcp-server-neon"],
|
||||
"env": {
|
||||
"NEON_API_KEY": "your-api-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Get your API key from: https://console.neon.tech/app/settings/api-keys
|
||||
|
||||
### Common MCP Operations
|
||||
|
||||
| Operation | What It Does |
|
||||
| ---------------------------- | ----------------------------- |
|
||||
| `list_projects` | Show all Neon projects |
|
||||
| `create_project` | Create a new project |
|
||||
| `run_sql` | Execute SQL queries |
|
||||
| `get_connection_string` | Get database connection URL |
|
||||
| `create_branch` | Create a database branch |
|
||||
| `prepare_database_migration` | Safely prepare schema changes |
|
||||
| `provision_neon_auth` | Set up Neon Auth |
|
||||
|
||||
For full MCP server documentation:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/ai/neon-mcp-server
|
||||
```
|
||||
|
||||
## Documentation Resources
|
||||
|
||||
| Topic | URL |
|
||||
| ------------------ | --------------------------------------------- |
|
||||
| CLI Init Command | https://neon.com/docs/reference/cli-init |
|
||||
| VSCode Extension | https://neon.com/docs/local/vscode-extension |
|
||||
| MCP Server | https://neon.com/docs/ai/neon-mcp-server |
|
||||
| Neon CLI Reference | https://neon.com/docs/reference/neon-cli |
|
||||
152
neon-postgres/references/features.md
Normal file
152
neon-postgres/references/features.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# Neon Features
|
||||
|
||||
Overview of Neon's key platform features. For detailed information, fetch the official docs.
|
||||
|
||||
## Branching
|
||||
|
||||
Create instant, copy-on-write clones of your database at any point in time. Branches are isolated environments perfect for development, testing, and preview deployments.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- Branches are instant (no data copying)
|
||||
- Copy-on-write means branches only store changes from parent
|
||||
- Use for: dev environments, staging, testing, preview deployments
|
||||
- Branches can have their own compute endpoint
|
||||
|
||||
**Use Cases:**
|
||||
|
||||
| Use Case | Description |
|
||||
| ------------------- | ------------------------------------------- |
|
||||
| Development | Each developer gets isolated branch |
|
||||
| Preview Deployments | Branch per PR/preview URL |
|
||||
| Testing | Reset test data by recreating branch |
|
||||
| Schema Migrations | Test migrations on branch before production |
|
||||
|
||||
If the Neon MCP server is available, you can use it to list and create branches. Otherwise, refer to the Neon CLI or Platform API.
|
||||
|
||||
## Autoscaling
|
||||
|
||||
Neon automatically scales compute resources based on workload demand.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/autoscaling
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- Scales between min and max compute units (CUs)
|
||||
- Responds to CPU and memory pressure
|
||||
- No manual intervention required
|
||||
- Configure limits per project or endpoint
|
||||
|
||||
## Scale to Zero
|
||||
|
||||
Databases automatically suspend after a period of inactivity, reducing costs to storage-only.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/scale-to-zero
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- Default suspend after 5 minutes of inactivity (configurable)
|
||||
- First query after suspend has ~500ms cold start
|
||||
- Storage is always maintained
|
||||
- Perfect for dev/staging environments with intermittent use
|
||||
|
||||
## Instant Restore
|
||||
|
||||
Restore your database to any point within your retention window without backups.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branch-restore
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- Point-in-time recovery without pre-configured backups
|
||||
- Restore window depends on plan (7-30 days)
|
||||
- Create branches from any point in history
|
||||
- Time Travel queries to view historical data
|
||||
|
||||
## Read Replicas
|
||||
|
||||
Create read-only compute endpoints to scale read workloads.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/read-replicas
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- Read replicas share storage with primary (no data duplication)
|
||||
- Instant creation
|
||||
- Independent scaling from primary
|
||||
- Use for: analytics, reporting, read-heavy workloads
|
||||
|
||||
## Connection Pooling
|
||||
|
||||
Built-in connection pooling via PgBouncer for efficient connection management.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/connect/connection-pooling
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- Enabled by adding `-pooler` to endpoint hostname
|
||||
- Transaction mode by default
|
||||
- Supports up to 10,000 concurrent connections
|
||||
- Essential for serverless environments
|
||||
|
||||
## IP Allow Lists
|
||||
|
||||
Restrict database access to specific IP addresses or ranges.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/ip-allow
|
||||
```
|
||||
|
||||
## Logical Replication
|
||||
|
||||
Replicate data to/from external Postgres databases.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/guides/logical-replication-guide
|
||||
```
|
||||
|
||||
## Neon Auth
|
||||
|
||||
Managed authentication that branches with your database.
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/auth/overview
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- Sign-in/sign-up with email, social providers (Google, GitHub)
|
||||
- Session management
|
||||
- UI components included
|
||||
- Branches with your database
|
||||
|
||||
For setup, see `neon-auth.md`. For auth + data API, see `neon-js.md`.
|
||||
|
||||
## Feature Documentation Reference
|
||||
|
||||
| Feature | Documentation | Resource |
|
||||
| ------------------- | ------------------------------------------------------- | -------------- |
|
||||
| Branching | https://neon.com/docs/introduction/branching | - |
|
||||
| Autoscaling | https://neon.com/docs/introduction/autoscaling | - |
|
||||
| Scale to Zero | https://neon.com/docs/introduction/scale-to-zero | - |
|
||||
| Instant Restore | https://neon.com/docs/introduction/branch-restore | - |
|
||||
| Read Replicas | https://neon.com/docs/introduction/read-replicas | - |
|
||||
| Connection Pooling | https://neon.com/docs/connect/connection-pooling | - |
|
||||
| IP Allow | https://neon.com/docs/introduction/ip-allow | - |
|
||||
| Logical Replication | https://neon.com/docs/guides/logical-replication-guide | - |
|
||||
| Neon Auth | https://neon.com/docs/auth/overview | `neon-auth.md` |
|
||||
| Data API | https://neon.com/docs/data-api/overview | `neon-js.md` |
|
||||
183
neon-postgres/references/getting-started.md
Normal file
183
neon-postgres/references/getting-started.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# Getting Started with Neon
|
||||
|
||||
Interactive guide to help users get started with Neon in their project. Sets up their Neon project (with a connection string) and connects their database to their code.
|
||||
|
||||
For the official getting started guide:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/get-started/signing-up
|
||||
```
|
||||
|
||||
## Interactive Setup Flow
|
||||
|
||||
### Step 1: Check Organizations and Projects
|
||||
|
||||
**First, check for organizations:**
|
||||
|
||||
- If they have 1 organization: Default to that organization
|
||||
- If they have multiple organizations: List all and ask which one to use
|
||||
|
||||
**Then, check for projects within the selected organization:**
|
||||
|
||||
- **No projects**: Ask if they want to create a new project
|
||||
- **1 project**: Ask "Would you like to use '{project_name}' or create a new one?"
|
||||
- **Multiple projects (<6)**: List all and let them choose
|
||||
- **Many projects (6+)**: List recent projects, offer to create new or specify by name/ID
|
||||
|
||||
### Step 2: Database Setup
|
||||
|
||||
**Get the connection string:**
|
||||
|
||||
- Use the MCP server to get the connection string for the selected project
|
||||
|
||||
**Configure it for their environment:**
|
||||
|
||||
- Most projects use a `.env` file with `DATABASE_URL`
|
||||
- For other setups, check project structure and ask
|
||||
|
||||
**Before modifying .env:**
|
||||
|
||||
1. Try to read the .env file first
|
||||
2. If readable: Use search_replace to update or append
|
||||
3. If unreadable: Use append command or show the line to add manually:
|
||||
|
||||
```
|
||||
DATABASE_URL=postgresql://user:password@host/database
|
||||
```
|
||||
|
||||
### Step 3: Install Dependencies
|
||||
|
||||
Recommend drivers based on deployment platform and runtime. For detailed guidance, see `connection-methods.md`.
|
||||
|
||||
**Quick Recommendations:**
|
||||
|
||||
| Environment | Driver | Install |
|
||||
| ------------------------ | -------------------------- | -------------------------------------- |
|
||||
| Vercel (Edge/Serverless) | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
|
||||
| Cloudflare Workers | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
|
||||
| AWS Lambda | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
|
||||
| Traditional Node.js | `pg` | `npm install pg` |
|
||||
| Long-running servers | `pg` with pooling | `npm install pg` |
|
||||
|
||||
For detailed serverless driver usage, see `neon-serverless.md`.
|
||||
For complex scenarios (multiple runtimes, hybrid architectures), reference `connection-methods.md`.
|
||||
|
||||
### Step 4: Understand the Project
|
||||
|
||||
**If it's an empty/new project:**
|
||||
Ask briefly (1-2 questions):
|
||||
|
||||
- What are they building?
|
||||
- Any specific technologies?
|
||||
|
||||
**If it's an established project:**
|
||||
Skip questions - infer from codebase. Update relevant code to use the driver.
|
||||
|
||||
### Step 5: Authentication (Optional)
|
||||
|
||||
**Skip if project doesn't need auth** (CLI tools, scripts, static sites).
|
||||
|
||||
**If project could benefit from auth:**
|
||||
Ask: "Does your app need user authentication? Neon Auth can handle sign-in/sign-up, social login, and session management."
|
||||
|
||||
**If they want auth:**
|
||||
|
||||
- Use MCP server `provision_neon_auth` tool
|
||||
- Guide through framework-specific setup
|
||||
- Configure environment variables
|
||||
- Set up basic auth code
|
||||
|
||||
For detailed auth setup, see `neon-auth.md`. For auth + database queries, see `neon-js.md`.
|
||||
|
||||
### Step 6: ORM Setup
|
||||
|
||||
**Check for existing ORM** (Prisma, Drizzle, TypeORM).
|
||||
|
||||
**If no ORM found:**
|
||||
Ask: "Want to set up an ORM for type-safe database queries?"
|
||||
|
||||
If yes, suggest based on project. If no, proceed with raw SQL.
|
||||
|
||||
For Drizzle ORM integration, see `neon-drizzle.md`.
|
||||
|
||||
### Step 7: Schema Setup
|
||||
|
||||
**Check for existing schema:**
|
||||
|
||||
- SQL migration files
|
||||
- ORM schemas (Prisma, Drizzle)
|
||||
- Database initialization scripts
|
||||
|
||||
**If existing schema found:**
|
||||
Ask: "Found existing schema definitions. Want to migrate these to your Neon database?"
|
||||
|
||||
**If no schema:**
|
||||
Ask if they want to:
|
||||
|
||||
1. Create a simple example schema (users table)
|
||||
2. Design a custom schema together
|
||||
3. Skip schema setup for now
|
||||
|
||||
**Example schema:**
|
||||
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id SERIAL PRIMARY KEY,
|
||||
email VARCHAR(255) UNIQUE NOT NULL,
|
||||
name VARCHAR(255),
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### Step 8: What's Next
|
||||
|
||||
"You're all set! Here are some things I can help with:
|
||||
|
||||
- Neon-specific features (branching, autoscaling, scale-to-zero)
|
||||
- Connection pooling for production
|
||||
- Writing queries or building API endpoints
|
||||
- Database migrations and schema changes
|
||||
- Performance optimization"
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. Never commit connection strings to version control
|
||||
2. Use environment variables for all credentials
|
||||
3. Prefer SSL connections (default in Neon)
|
||||
4. Use least-privilege database roles
|
||||
5. Rotate API keys and passwords regularly
|
||||
|
||||
## Resume Support
|
||||
|
||||
If user says "Continue with Neon setup", check what's already configured:
|
||||
|
||||
- MCP server connection
|
||||
- .env file with DATABASE_URL
|
||||
- Dependencies installed
|
||||
- Schema created
|
||||
|
||||
Then resume from where they left off.
|
||||
|
||||
## Developer Tools
|
||||
|
||||
For the best development experience, set up Neon's developer tools:
|
||||
|
||||
```bash
|
||||
npx neon init
|
||||
```
|
||||
|
||||
This installs the VSCode extension and configures the MCP server for AI-assisted development.
|
||||
|
||||
For detailed setup instructions, see `devtools.md`.
|
||||
|
||||
## Documentation Resources
|
||||
|
||||
| Topic | URL |
|
||||
| ------------------ | --------------------------------------------------- |
|
||||
| Getting Started | https://neon.com/docs/get-started/signing-up |
|
||||
| Connecting to Neon | https://neon.com/docs/connect/connect-intro |
|
||||
| Connection String | https://neon.com/docs/connect/connect-from-any-app |
|
||||
| Frameworks Guide | https://neon.com/docs/get-started/frameworks |
|
||||
| ORMs Guide | https://neon.com/docs/get-started/orms |
|
||||
| VSCode Extension | https://neon.com/docs/local/vscode-extension |
|
||||
| MCP Server | https://neon.com/docs/ai/neon-mcp-server |
|
||||
141
neon-postgres/references/neon-auth.md
Normal file
141
neon-postgres/references/neon-auth.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Neon Auth
|
||||
|
||||
Neon Auth provides authentication for your application. It's available as:
|
||||
|
||||
- `@neondatabase/auth` - Auth only (smaller bundle)
|
||||
- `@neondatabase/neon-js` - Auth + Data API (full SDK, see `neon-js.md`)
|
||||
|
||||
For official documentation:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/auth/overview
|
||||
```
|
||||
|
||||
## Package Selection
|
||||
|
||||
| Need | Package | Bundle |
|
||||
| ----------------------- | ----------------------- | ------- |
|
||||
| Auth only | `@neondatabase/auth` | Smaller |
|
||||
| Auth + Database queries | `@neondatabase/neon-js` | Full |
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Auth only
|
||||
npm install @neondatabase/auth
|
||||
|
||||
# Auth + Data API
|
||||
npm install @neondatabase/neon-js
|
||||
```
|
||||
|
||||
## Quick Setup Patterns
|
||||
|
||||
### Next.js App Router
|
||||
|
||||
**1. API Route Handler:**
|
||||
|
||||
```typescript
|
||||
// app/api/auth/[...path]/route.ts
|
||||
import { authApiHandler } from "@neondatabase/auth/next";
|
||||
export const { GET, POST } = authApiHandler();
|
||||
```
|
||||
|
||||
**2. Auth Client:**
|
||||
|
||||
```typescript
|
||||
// lib/auth/client.ts
|
||||
import { createAuthClient } from "@neondatabase/auth/next";
|
||||
export const authClient = createAuthClient();
|
||||
```
|
||||
|
||||
**3. Use in Components:**
|
||||
|
||||
```typescript
|
||||
"use client";
|
||||
import { authClient } from "@/lib/auth/client";
|
||||
|
||||
function AuthStatus() {
|
||||
const session = authClient.useSession();
|
||||
if (session.isPending) return <div>Loading...</div>;
|
||||
if (!session.data) return <SignInButton />;
|
||||
return <div>Hello, {session.data.user.name}</div>;
|
||||
}
|
||||
```
|
||||
|
||||
### React SPA
|
||||
|
||||
```typescript
|
||||
import { createAuthClient } from "@neondatabase/auth";
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/auth/react/adapters";
|
||||
|
||||
const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL, {
|
||||
adapter: BetterAuthReactAdapter(),
|
||||
});
|
||||
```
|
||||
|
||||
### Node.js Backend
|
||||
|
||||
```typescript
|
||||
import { createAuthClient } from "@neondatabase/auth";
|
||||
|
||||
const auth = createAuthClient(process.env.NEON_AUTH_URL!);
|
||||
await auth.signIn.email({ email, password });
|
||||
const session = await auth.getSession();
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
# Next.js (.env.local)
|
||||
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
NEXT_PUBLIC_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
|
||||
# Vite/React (.env)
|
||||
VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
```
|
||||
|
||||
## Sub-Resources
|
||||
|
||||
For detailed documentation:
|
||||
|
||||
| Topic | Resource |
|
||||
| ------------------------ | ------------------------------ |
|
||||
| Next.js App Router setup | `neon-auth/setup-nextjs.md` |
|
||||
| React SPA setup | `neon-auth/setup-react-spa.md` |
|
||||
| Auth methods reference | `neon-auth/auth-methods.md` |
|
||||
| UI components | `neon-auth/ui-components.md` |
|
||||
| Common mistakes | `neon-auth/common-mistakes.md` |
|
||||
|
||||
## Key Imports
|
||||
|
||||
```typescript
|
||||
// Auth client (Next.js)
|
||||
import { authApiHandler, createAuthClient } from "@neondatabase/auth/next";
|
||||
|
||||
// Auth client (vanilla)
|
||||
import { createAuthClient } from "@neondatabase/auth";
|
||||
|
||||
// React adapter (NOT from main entry)
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/auth/react/adapters";
|
||||
|
||||
// UI components
|
||||
import {
|
||||
NeonAuthUIProvider,
|
||||
AuthView,
|
||||
SignInForm,
|
||||
} from "@neondatabase/auth/react/ui";
|
||||
import { authViewPaths } from "@neondatabase/auth/react/ui/server";
|
||||
|
||||
// CSS
|
||||
import "@neondatabase/auth/ui/css";
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
1. **Wrong adapter import**: Import `BetterAuthReactAdapter` from `auth/react/adapters` subpath
|
||||
2. **Forgetting to call adapter**: Use `BetterAuthReactAdapter()` with parentheses
|
||||
3. **Missing CSS**: Import from `ui/css` or `ui/tailwind` (not both)
|
||||
4. **Missing "use client"**: Required for components using `useSession()`
|
||||
5. **Wrong createAuthClient signature**: First arg is URL: `createAuthClient(url, { adapter })`
|
||||
|
||||
See `neon-auth/common-mistakes.md` for detailed examples.
|
||||
241
neon-postgres/references/neon-auth/auth-methods.md
Normal file
241
neon-postgres/references/neon-auth/auth-methods.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# Neon Auth - Auth Methods Reference
|
||||
|
||||
Complete reference for authentication methods, session management, and error handling.
|
||||
|
||||
## Auth Methods
|
||||
|
||||
### Sign Up
|
||||
|
||||
```typescript
|
||||
await auth.signUp.email({
|
||||
email: "user@example.com",
|
||||
password: "securepassword",
|
||||
name: "John Doe", // Optional
|
||||
});
|
||||
```
|
||||
|
||||
### Sign In
|
||||
|
||||
```typescript
|
||||
// Email/password
|
||||
await auth.signIn.email({
|
||||
email: "user@example.com",
|
||||
password: "securepassword",
|
||||
});
|
||||
|
||||
// Social (Google, GitHub)
|
||||
await auth.signIn.social({
|
||||
provider: "google", // or "github"
|
||||
callbackURL: "/dashboard",
|
||||
});
|
||||
```
|
||||
|
||||
### Sign Out
|
||||
|
||||
```typescript
|
||||
await auth.signOut();
|
||||
```
|
||||
|
||||
### Get Session
|
||||
|
||||
```typescript
|
||||
// Async (Node.js, server components)
|
||||
const session = await auth.getSession();
|
||||
|
||||
// React hook (client components)
|
||||
const session = auth.useSession();
|
||||
// Returns: { data: Session | null, isPending: boolean }
|
||||
```
|
||||
|
||||
## Session Data Structure
|
||||
|
||||
```typescript
|
||||
interface Session {
|
||||
user: {
|
||||
id: string;
|
||||
name: string | null;
|
||||
email: string;
|
||||
image: string | null;
|
||||
emailVerified: boolean;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
};
|
||||
session: {
|
||||
id: string;
|
||||
expiresAt: Date;
|
||||
token: string;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
userId: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```typescript
|
||||
const { error } = await auth.signIn.email({ email, password });
|
||||
|
||||
if (error) {
|
||||
switch (error.code) {
|
||||
case "INVALID_EMAIL_OR_PASSWORD":
|
||||
showError("Invalid email or password");
|
||||
break;
|
||||
case "EMAIL_NOT_VERIFIED":
|
||||
showError("Please verify your email");
|
||||
break;
|
||||
case "USER_NOT_FOUND":
|
||||
showError("User not found");
|
||||
break;
|
||||
case "TOO_MANY_REQUESTS":
|
||||
showError("Too many attempts. Please wait.");
|
||||
break;
|
||||
default:
|
||||
showError("Authentication failed");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Building Auth Pages
|
||||
|
||||
### Use AuthView (Recommended for React Apps)
|
||||
|
||||
For authentication pages, use the pre-built `AuthView` component instead of building custom forms.
|
||||
|
||||
**What AuthView provides:**
|
||||
|
||||
- Sign-in, sign-up, password reset, magic link pages
|
||||
- Social providers (Google, GitHub) - requires TWO configurations: enable in Neon Console AND add `social` prop to NeonAuthUIProvider
|
||||
- Form validation, error handling, loading states
|
||||
- Consistent styling via CSS variables
|
||||
|
||||
**Setup (Next.js App Router):**
|
||||
|
||||
1. **Import CSS** (in `app/layout.tsx` or `app/globals.css`):
|
||||
|
||||
```tsx
|
||||
import "@neondatabase/auth/ui/css";
|
||||
```
|
||||
|
||||
2. **Wrap app with provider** (create `app/auth-provider.tsx`):
|
||||
|
||||
```tsx
|
||||
"use client";
|
||||
import { NeonAuthUIProvider } from "@neondatabase/auth/react/ui";
|
||||
import { authClient } from "@/lib/auth/client";
|
||||
import { useRouter } from "next/navigation";
|
||||
import Link from "next/link";
|
||||
|
||||
export function AuthProvider({ children }: { children: React.ReactNode }) {
|
||||
const router = useRouter();
|
||||
return (
|
||||
<NeonAuthUIProvider
|
||||
authClient={authClient}
|
||||
navigate={router.push}
|
||||
replace={router.replace}
|
||||
onSessionChange={() => router.refresh()}
|
||||
Link={Link}
|
||||
>
|
||||
{children}
|
||||
</NeonAuthUIProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
3. **Create auth page** (`app/auth/[path]/page.tsx`):
|
||||
|
||||
```tsx
|
||||
import { AuthView } from "@neondatabase/auth/react/ui";
|
||||
import { authViewPaths } from "@neondatabase/auth/react/ui/server";
|
||||
|
||||
export function generateStaticParams() {
|
||||
return Object.values(authViewPaths).map((path) => ({ path }));
|
||||
}
|
||||
|
||||
export default async function AuthPage({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ path: string }>;
|
||||
}) {
|
||||
const { path } = await params;
|
||||
return <AuthView pathname={path} />;
|
||||
}
|
||||
```
|
||||
|
||||
**Result:** You now have `/auth/sign-in`, `/auth/sign-up`, `/auth/forgot-password`, etc.
|
||||
|
||||
**Available paths:** `"sign-in"`, `"sign-up"`, `"forgot-password"`, `"reset-password"`, `"magic-link"`, `"two-factor"`, `"callback"`, `"sign-out"`
|
||||
|
||||
### When to Use Low-Level Methods Instead
|
||||
|
||||
Use `authClient.signIn.email()`, `authClient.signUp.email()` directly if:
|
||||
|
||||
- **Node.js backend** - No React, server-side auth only
|
||||
- **Custom design system** - Your design team provides form components
|
||||
- **Mobile/CLI apps** - Non-web frontends
|
||||
- **Headless auth** - Testing or non-standard flows
|
||||
|
||||
For standard React web apps, **use AuthView**.
|
||||
|
||||
### Common Anti-Pattern
|
||||
|
||||
```tsx
|
||||
// ❌ Don't build custom forms unless you have specific requirements
|
||||
function CustomSignInPage() {
|
||||
const [email, setEmail] = useState("");
|
||||
const [password, setPassword] = useState("");
|
||||
const [error, setError] = useState("");
|
||||
const [loading, setLoading] = useState(false);
|
||||
|
||||
const handleSubmit = async (e) => {
|
||||
e.preventDefault();
|
||||
setLoading(true);
|
||||
const { error } = await authClient.signIn.email({ email, password });
|
||||
if (error) setError(error.message);
|
||||
setLoading(false);
|
||||
};
|
||||
|
||||
// ... 50+ more lines of form JSX, validation, error display
|
||||
}
|
||||
|
||||
// ✅ Use AuthView instead - one component handles everything
|
||||
<AuthView pathname="sign-in" />;
|
||||
```
|
||||
|
||||
## Styling
|
||||
|
||||
Neon Auth UI **automatically inherits your app's existing theme**. If you have CSS variables like `--primary`, `--background`, etc. defined (from Tailwind, shadcn/ui, or custom CSS), auth components use them with no configuration.
|
||||
|
||||
**Key features:**
|
||||
|
||||
- **Automatic inheritance**: Uses your existing `--primary`, `--background`, etc.
|
||||
- **No conflicts**: Auth styles are in `@layer neon-auth`, so your styles always win
|
||||
- **Import order doesn't matter**: CSS layers handle priority automatically
|
||||
|
||||
### Integration with shadcn/ui
|
||||
|
||||
If you use shadcn/ui or similar libraries that define `--primary`, `--background`, etc., Neon Auth will automatically inherit those colors. No additional configuration needed.
|
||||
|
||||
### Use Existing CSS Variables
|
||||
|
||||
When creating custom components, use CSS variables for consistency:
|
||||
|
||||
| Variable | Purpose |
|
||||
| ----------------------------------- | ----------------------- |
|
||||
| `--background`, `--foreground` | Page background/text |
|
||||
| `--card`, `--card-foreground` | Card surfaces |
|
||||
| `--primary`, `--primary-foreground` | Primary buttons/actions |
|
||||
| `--muted`, `--muted-foreground` | Muted/subtle elements |
|
||||
| `--border`, `--ring` | Borders and focus rings |
|
||||
| `--radius` | Border radius |
|
||||
|
||||
### Auth-Specific Customization
|
||||
|
||||
To customize auth components differently from your main app, use `--neon-*` prefix:
|
||||
|
||||
```css
|
||||
:root {
|
||||
--primary: oklch(0.55 0.25 250); /* Your app's blue */
|
||||
--neon-primary: oklch(0.55 0.18 145); /* Auth uses green */
|
||||
}
|
||||
```
|
||||
225
neon-postgres/references/neon-auth/common-mistakes.md
Normal file
225
neon-postgres/references/neon-auth/common-mistakes.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Neon Auth - Common Mistakes
|
||||
|
||||
Reference guide for common mistakes when using `@neondatabase/auth` or `@neondatabase/neon-js`.
|
||||
|
||||
## Import Mistakes
|
||||
|
||||
### BetterAuthReactAdapter Subpath Requirement
|
||||
|
||||
`BetterAuthReactAdapter` is **NOT** exported from the main package entry. You must import it from the subpath.
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```typescript
|
||||
// These will NOT work
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/neon-js";
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/auth";
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```typescript
|
||||
// For @neondatabase/neon-js
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react/adapters";
|
||||
|
||||
// For @neondatabase/auth
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/auth/react/adapters";
|
||||
```
|
||||
|
||||
**Why:** The React adapter has React-specific dependencies and is tree-shaken out of the main bundle. Using subpath exports keeps the main bundle smaller for non-React environments.
|
||||
|
||||
### Adapter Factory Functions
|
||||
|
||||
All adapters are **factory functions** that must be called with `()`.
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```typescript
|
||||
const client = createClient({
|
||||
auth: {
|
||||
adapter: BetterAuthReactAdapter, // Missing ()
|
||||
url: process.env.NEON_AUTH_URL!,
|
||||
},
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```typescript
|
||||
const client = createClient({
|
||||
auth: {
|
||||
adapter: BetterAuthReactAdapter(), // Called as function
|
||||
url: process.env.NEON_AUTH_URL!,
|
||||
},
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
This applies to all adapters:
|
||||
|
||||
- `BetterAuthReactAdapter()`
|
||||
- `BetterAuthVanillaAdapter()`
|
||||
- `SupabaseAuthAdapter()`
|
||||
|
||||
---
|
||||
|
||||
## CSS Import Mistakes
|
||||
|
||||
Auth UI components require CSS. Choose **ONE** method based on your project.
|
||||
|
||||
### With Tailwind v4
|
||||
|
||||
```css
|
||||
/* In app/globals.css */
|
||||
@import "tailwindcss";
|
||||
@import "@neondatabase/neon-js/ui/tailwind";
|
||||
/* Or: @import '@neondatabase/auth/ui/tailwind'; */
|
||||
```
|
||||
|
||||
### Without Tailwind
|
||||
|
||||
```typescript
|
||||
// In app/layout.tsx
|
||||
import "@neondatabase/neon-js/ui/css";
|
||||
// Or: import "@neondatabase/auth/ui/css";
|
||||
```
|
||||
|
||||
### Never Import Both
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```css
|
||||
/* Causes ~94KB of duplicate styles */
|
||||
@import "@neondatabase/neon-js/ui/css";
|
||||
@import "@neondatabase/neon-js/ui/tailwind";
|
||||
```
|
||||
|
||||
**Why:** The `ui/css` import includes pre-built CSS (~47KB). The `ui/tailwind` import provides Tailwind tokens (~2KB) that generate similar styles. Using both doubles your CSS bundle.
|
||||
|
||||
---
|
||||
|
||||
## Configuration Mistakes
|
||||
|
||||
### Wrong createAuthClient Signature
|
||||
|
||||
The `createAuthClient` function takes the URL as the first argument, not as a property in an options object.
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```typescript
|
||||
// This will NOT work
|
||||
createAuthClient({ baseURL: url });
|
||||
createAuthClient({ url: myUrl });
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```typescript
|
||||
// Vanilla client - URL as first arg
|
||||
createAuthClient(url);
|
||||
|
||||
// With adapter - URL as first arg, options as second
|
||||
createAuthClient(url, { adapter: BetterAuthReactAdapter() });
|
||||
|
||||
// Next.js client - no arguments (uses env vars automatically)
|
||||
import { createAuthClient } from "@neondatabase/auth/next";
|
||||
const authClient = createAuthClient();
|
||||
```
|
||||
|
||||
### Missing Environment Variables
|
||||
|
||||
**Required for Next.js:**
|
||||
|
||||
```bash
|
||||
# .env.local
|
||||
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
NEXT_PUBLIC_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
|
||||
# For neon-js (auth + data)
|
||||
NEON_DATA_API_URL=https://ep-xxx.apirest.c-2.us-east-2.aws.neon.build/dbname/rest/v1
|
||||
```
|
||||
|
||||
**Required for Vite/React SPA:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
VITE_NEON_DATA_API_URL=https://ep-xxx.apirest.c-2.us-east-2.aws.neon.build/dbname/rest/v1
|
||||
```
|
||||
|
||||
**Important:**
|
||||
|
||||
- `NEON_AUTH_BASE_URL` - Server-side auth
|
||||
- `NEXT_PUBLIC_*` prefix - Required for client-side access in Next.js
|
||||
- `VITE_*` prefix - Required for client-side access in Vite
|
||||
- Restart dev server after adding env vars
|
||||
|
||||
---
|
||||
|
||||
## Usage Mistakes
|
||||
|
||||
### Missing "use client" Directive
|
||||
|
||||
Client components using `useSession()` need the `"use client"` directive.
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```typescript
|
||||
// Missing directive - will cause hydration errors
|
||||
import { authClient } from "@/lib/auth/client";
|
||||
|
||||
function AuthStatus() {
|
||||
const session = authClient.useSession();
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```typescript
|
||||
"use client";
|
||||
|
||||
import { authClient } from "@/lib/auth/client";
|
||||
|
||||
function AuthStatus() {
|
||||
const session = authClient.useSession();
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Wrong API for Adapter
|
||||
|
||||
Each adapter has its own API style. Don't mix them.
|
||||
|
||||
**Wrong - BetterAuth API with SupabaseAuthAdapter:**
|
||||
|
||||
```typescript
|
||||
const client = createClient({
|
||||
auth: { adapter: SupabaseAuthAdapter(), url },
|
||||
dataApi: { url },
|
||||
});
|
||||
|
||||
// This won't work with SupabaseAuthAdapter
|
||||
await client.auth.signIn.email({ email, password });
|
||||
```
|
||||
|
||||
**Correct - Supabase API with SupabaseAuthAdapter:**
|
||||
|
||||
```typescript
|
||||
const client = createClient({
|
||||
auth: { adapter: SupabaseAuthAdapter(), url },
|
||||
dataApi: { url },
|
||||
});
|
||||
|
||||
// Use Supabase-style methods
|
||||
await client.auth.signInWithPassword({ email, password });
|
||||
```
|
||||
|
||||
**API Reference by Adapter:**
|
||||
|
||||
| Adapter | Sign In | Sign Up | Get Session |
|
||||
| ------------------------ | ----------------------------------------- | ----------------------------------- | ------------------------------- |
|
||||
| BetterAuthVanillaAdapter | `signIn.email({ email, password })` | `signUp.email({ email, password })` | `getSession()` |
|
||||
| BetterAuthReactAdapter | `signIn.email({ email, password })` | `signUp.email({ email, password })` | `useSession()` / `getSession()` |
|
||||
| SupabaseAuthAdapter | `signInWithPassword({ email, password })` | `signUp({ email, password })` | `getSession()` |
|
||||
110
neon-postgres/references/neon-auth/setup-nextjs.md
Normal file
110
neon-postgres/references/neon-auth/setup-nextjs.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Neon Auth Setup - Next.js App Router
|
||||
|
||||
Complete setup instructions for Neon Auth in Next.js App Router applications.
|
||||
|
||||
---
|
||||
|
||||
## 1. Install Package
|
||||
|
||||
```bash
|
||||
npm install @neondatabase/auth
|
||||
# Or: npm install @neondatabase/neon-js
|
||||
```
|
||||
|
||||
## 2. Environment Variables
|
||||
|
||||
Create or update `.env.local`:
|
||||
|
||||
```bash
|
||||
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
NEXT_PUBLIC_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
```
|
||||
|
||||
**Important:** Both variables are needed:
|
||||
|
||||
- `NEON_AUTH_BASE_URL` - Used by server-side API routes
|
||||
- `NEXT_PUBLIC_NEON_AUTH_URL` - Used by client-side components (prefixed with NEXT*PUBLIC*)
|
||||
|
||||
**Where to find your Auth URL:**
|
||||
|
||||
1. Go to your Neon project dashboard
|
||||
2. Navigate to the "Auth" tab
|
||||
3. Copy the Auth URL
|
||||
|
||||
## 3. API Route Handler
|
||||
|
||||
Create `app/api/auth/[...path]/route.ts`:
|
||||
|
||||
```typescript
|
||||
import { authApiHandler } from "@neondatabase/auth/next";
|
||||
// Or: import { authApiHandler } from "@neondatabase/neon-js/auth/next";
|
||||
|
||||
export const { GET, POST } = authApiHandler();
|
||||
```
|
||||
|
||||
This creates endpoints for:
|
||||
|
||||
- `/api/auth/sign-in` - Sign in
|
||||
- `/api/auth/sign-up` - Sign up
|
||||
- `/api/auth/sign-out` - Sign out
|
||||
- `/api/auth/session` - Get session
|
||||
- And other auth-related endpoints
|
||||
|
||||
## 4. Auth Client Configuration
|
||||
|
||||
Create `lib/auth/client.ts`:
|
||||
|
||||
```typescript
|
||||
import { createAuthClient } from "@neondatabase/auth/next";
|
||||
// Or: import { createAuthClient } from "@neondatabase/neon-js/auth/next";
|
||||
|
||||
export const authClient = createAuthClient();
|
||||
```
|
||||
|
||||
## 5. Use in Components
|
||||
|
||||
```typescript
|
||||
"use client";
|
||||
|
||||
import { authClient } from "@/lib/auth/client";
|
||||
|
||||
function AuthStatus() {
|
||||
const session = authClient.useSession();
|
||||
|
||||
if (session.isPending) return <div>Loading...</div>;
|
||||
if (!session.data) return <SignInButton />;
|
||||
|
||||
return (
|
||||
<div>
|
||||
<p>Hello, {session.data.user.name}</p>
|
||||
<button onClick={() => authClient.signOut()}>Sign Out</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
function SignInButton() {
|
||||
return (
|
||||
<button onClick={() => authClient.signIn.email({
|
||||
email: "user@example.com",
|
||||
password: "password"
|
||||
})}>
|
||||
Sign In
|
||||
</button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 6. UI Provider Setup (Optional)
|
||||
|
||||
For pre-built UI components (AuthView, UserButton, etc.), see `ui-components.md`.
|
||||
|
||||
---
|
||||
|
||||
## Package Selection
|
||||
|
||||
| Need | Package | Bundle Size |
|
||||
| ----------------------- | ----------------------- | --------------- |
|
||||
| Auth only | `@neondatabase/auth` | Smaller (~50KB) |
|
||||
| Auth + Database queries | `@neondatabase/neon-js` | Full (~150KB) |
|
||||
|
||||
**Recommendation:** Use `@neondatabase/auth` if you only need authentication. Use `@neondatabase/neon-js` if you also need PostgREST-style database queries.
|
||||
248
neon-postgres/references/neon-auth/setup-react-spa.md
Normal file
248
neon-postgres/references/neon-auth/setup-react-spa.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# Neon Auth Setup - React SPA (Vite)
|
||||
|
||||
Complete setup instructions for Neon Auth in React Single Page Applications (Vite, Create React App, etc.).
|
||||
|
||||
---
|
||||
|
||||
## 1. Install Package
|
||||
|
||||
```bash
|
||||
npm install @neondatabase/auth
|
||||
# Or: npm install @neondatabase/neon-js
|
||||
npm install react-router-dom # Required for UI components
|
||||
```
|
||||
|
||||
## 2. Environment Variables
|
||||
|
||||
Create or update `.env`:
|
||||
|
||||
**For Vite:**
|
||||
|
||||
```bash
|
||||
VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
```
|
||||
|
||||
**For Create React App:**
|
||||
|
||||
```bash
|
||||
REACT_APP_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
```
|
||||
|
||||
**Where to find your Auth URL:**
|
||||
|
||||
1. Go to your Neon project dashboard
|
||||
2. Navigate to the "Auth" tab
|
||||
3. Copy the Auth URL
|
||||
|
||||
## 3. Auth Client Configuration
|
||||
|
||||
Create `src/lib/auth-client.ts`:
|
||||
|
||||
**For `@neondatabase/auth`:**
|
||||
|
||||
```typescript
|
||||
import { createAuthClient } from "@neondatabase/auth";
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/auth/react/adapters";
|
||||
|
||||
export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL, {
|
||||
adapter: BetterAuthReactAdapter(),
|
||||
});
|
||||
```
|
||||
|
||||
**For `@neondatabase/neon-js`:**
|
||||
|
||||
```typescript
|
||||
import { createClient } from "@neondatabase/neon-js";
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react/adapters";
|
||||
|
||||
export const client = createClient({
|
||||
auth: {
|
||||
adapter: BetterAuthReactAdapter(),
|
||||
url: import.meta.env.VITE_NEON_AUTH_URL,
|
||||
},
|
||||
dataApi: {
|
||||
url: import.meta.env.VITE_NEON_DATA_API_URL,
|
||||
},
|
||||
});
|
||||
|
||||
export const authClient = client.auth;
|
||||
```
|
||||
|
||||
**Critical:**
|
||||
|
||||
- `BetterAuthReactAdapter` must be imported from the `/react/adapters` subpath
|
||||
- The adapter must be called as a function: `BetterAuthReactAdapter()`
|
||||
|
||||
## 4. Use in Components
|
||||
|
||||
```typescript
|
||||
import { authClient } from "./lib/auth-client";
|
||||
|
||||
function App() {
|
||||
const session = authClient.useSession();
|
||||
|
||||
if (session.isPending) return <div>Loading...</div>;
|
||||
if (!session.data) return <LoginForm />;
|
||||
|
||||
return <Dashboard user={session.data.user} />;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. UI Provider Setup (Optional)
|
||||
|
||||
Skip this section if you're building custom auth forms. Use this if you want pre-built UI components.
|
||||
|
||||
### 5a. Import CSS
|
||||
|
||||
**CRITICAL:** Choose ONE import method. Never import both - it causes duplicate styles.
|
||||
|
||||
**Check if the project uses Tailwind CSS** by looking for:
|
||||
|
||||
- `tailwind.config.js` or `tailwind.config.ts` in the project root
|
||||
- `@import 'tailwindcss'` or `@tailwind` directives in CSS files
|
||||
- `tailwindcss` in package.json dependencies
|
||||
|
||||
**If NOT using Tailwind** - Add to `src/main.tsx` or entry point:
|
||||
|
||||
```typescript
|
||||
import "@neondatabase/auth/ui/css";
|
||||
```
|
||||
|
||||
**If using Tailwind CSS v4** - Add to main CSS file (e.g., index.css):
|
||||
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
@import "@neondatabase/auth/ui/tailwind";
|
||||
```
|
||||
|
||||
### 5b. Update main.tsx with BrowserRouter
|
||||
|
||||
```tsx
|
||||
import { createRoot } from "react-dom/client";
|
||||
import { BrowserRouter } from "react-router-dom";
|
||||
import "@neondatabase/auth/ui/css"; // if not using Tailwind
|
||||
import App from "./App";
|
||||
import { Providers } from "./providers";
|
||||
|
||||
createRoot(document.getElementById("root")!).render(
|
||||
<BrowserRouter>
|
||||
<Providers>
|
||||
<App />
|
||||
</Providers>
|
||||
</BrowserRouter>,
|
||||
);
|
||||
```
|
||||
|
||||
### 5c. Create Auth Provider
|
||||
|
||||
Create `src/providers.tsx`:
|
||||
|
||||
```tsx
|
||||
import { NeonAuthUIProvider } from "@neondatabase/auth/react/ui";
|
||||
import { useNavigate, Link as RouterLink } from "react-router-dom";
|
||||
import { authClient } from "./lib/auth-client";
|
||||
import type { ReactNode } from "react";
|
||||
|
||||
// Adapter for react-router-dom Link
|
||||
function Link({
|
||||
href,
|
||||
...props
|
||||
}: { href: string } & React.AnchorHTMLAttributes<HTMLAnchorElement>) {
|
||||
return <RouterLink to={href} {...props} />;
|
||||
}
|
||||
|
||||
export function Providers({ children }: { children: ReactNode }) {
|
||||
const navigate = useNavigate();
|
||||
|
||||
return (
|
||||
<NeonAuthUIProvider
|
||||
authClient={authClient}
|
||||
navigate={(path) => navigate(path)}
|
||||
replace={(path) => navigate(path, { replace: true })}
|
||||
onSessionChange={() => {
|
||||
// Optional: refresh data or invalidate cache
|
||||
}}
|
||||
Link={Link}
|
||||
social={{
|
||||
providers: ["google", "github"],
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</NeonAuthUIProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Provider props explained:**
|
||||
|
||||
- `navigate`: Function to navigate to a new route
|
||||
- `replace`: Function to replace current route (for redirects)
|
||||
- `onSessionChange`: Callback when auth state changes (useful for cache invalidation)
|
||||
- `Link`: Adapter component for react-router-dom's Link
|
||||
- `social`: Show Google and GitHub sign-in buttons (both enabled by default in Neon)
|
||||
|
||||
### 5d. Add Routes to App.tsx
|
||||
|
||||
```tsx
|
||||
import { Routes, Route, useParams } from "react-router-dom";
|
||||
import {
|
||||
AuthView,
|
||||
UserButton,
|
||||
SignedIn,
|
||||
SignedOut,
|
||||
} from "@neondatabase/auth/react/ui";
|
||||
|
||||
// Auth page - handles /auth/sign-in, /auth/sign-up, etc.
|
||||
function AuthPage() {
|
||||
const { pathname } = useParams();
|
||||
return (
|
||||
<div className="flex min-h-screen items-center justify-center">
|
||||
<AuthView pathname={pathname} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// Simple navbar example
|
||||
function Navbar() {
|
||||
return (
|
||||
<nav className="flex items-center justify-between p-4 border-b">
|
||||
<a href="/">My App</a>
|
||||
<div className="flex items-center gap-4">
|
||||
<SignedOut>
|
||||
<a href="/auth/sign-in">Sign In</a>
|
||||
</SignedOut>
|
||||
<SignedIn>
|
||||
<UserButton />
|
||||
</SignedIn>
|
||||
</div>
|
||||
</nav>
|
||||
);
|
||||
}
|
||||
|
||||
function HomePage() {
|
||||
return <div>Welcome to My App!</div>;
|
||||
}
|
||||
|
||||
export default function App() {
|
||||
return (
|
||||
<>
|
||||
<Navbar />
|
||||
<Routes>
|
||||
<Route path="/" element={<HomePage />} />
|
||||
<Route path="/auth/:pathname" element={<AuthPage />} />
|
||||
</Routes>
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Auth routes created:**
|
||||
|
||||
- `/auth/sign-in` - Sign in page
|
||||
- `/auth/sign-up` - Sign up page
|
||||
- `/auth/forgot-password` - Password reset request
|
||||
- `/auth/reset-password` - Set new password
|
||||
- `/auth/sign-out` - Sign out
|
||||
- `/auth/callback` - OAuth callback (internal)
|
||||
215
neon-postgres/references/neon-auth/ui-components.md
Normal file
215
neon-postgres/references/neon-auth/ui-components.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Neon Auth - UI Components Reference
|
||||
|
||||
Pre-built UI components for authentication flows.
|
||||
|
||||
## Available Components
|
||||
|
||||
- `AuthView` - Complete auth pages (sign-in, sign-up, forgot-password, etc.) - **use this first**
|
||||
- `SignedIn` / `SignedOut` - Conditional rendering based on auth state
|
||||
- `UserButton` - User avatar with dropdown menu
|
||||
- `NeonAuthUIProvider` - Required wrapper for UI components
|
||||
|
||||
## CSS Import
|
||||
|
||||
**CRITICAL:** Choose ONE import method. Never import both.
|
||||
|
||||
**Without Tailwind:**
|
||||
|
||||
```typescript
|
||||
// In app/layout.tsx or entry point
|
||||
import "@neondatabase/auth/ui/css";
|
||||
```
|
||||
|
||||
**With Tailwind v4:**
|
||||
|
||||
```css
|
||||
/* In app/globals.css */
|
||||
@import "tailwindcss";
|
||||
@import "@neondatabase/auth/ui/tailwind";
|
||||
```
|
||||
|
||||
## NeonAuthUIProvider Setup
|
||||
|
||||
### Next.js App Router
|
||||
|
||||
```tsx
|
||||
"use client";
|
||||
import { NeonAuthUIProvider } from "@neondatabase/auth/react/ui";
|
||||
import { authClient } from "@/lib/auth/client";
|
||||
import { useRouter } from "next/navigation";
|
||||
import Link from "next/link";
|
||||
|
||||
export function AuthProvider({ children }: { children: React.ReactNode }) {
|
||||
const router = useRouter();
|
||||
return (
|
||||
<NeonAuthUIProvider
|
||||
authClient={authClient}
|
||||
navigate={router.push}
|
||||
replace={router.replace}
|
||||
onSessionChange={() => router.refresh()}
|
||||
Link={Link}
|
||||
social={{
|
||||
providers: ["google", "github"],
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</NeonAuthUIProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### React SPA with react-router-dom
|
||||
|
||||
```tsx
|
||||
import { NeonAuthUIProvider } from "@neondatabase/auth/react/ui";
|
||||
import { useNavigate, Link as RouterLink } from "react-router-dom";
|
||||
import { authClient } from "./lib/auth-client";
|
||||
|
||||
function Link({
|
||||
href,
|
||||
...props
|
||||
}: { href: string } & React.AnchorHTMLAttributes<HTMLAnchorElement>) {
|
||||
return <RouterLink to={href} {...props} />;
|
||||
}
|
||||
|
||||
export function Providers({ children }: { children: React.ReactNode }) {
|
||||
const navigate = useNavigate();
|
||||
|
||||
return (
|
||||
<NeonAuthUIProvider
|
||||
authClient={authClient}
|
||||
navigate={(path) => navigate(path)}
|
||||
replace={(path) => navigate(path, { replace: true })}
|
||||
onSessionChange={() => {}}
|
||||
Link={Link}
|
||||
social={{
|
||||
providers: ["google", "github"],
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</NeonAuthUIProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## AuthView Component
|
||||
|
||||
Renders complete authentication pages.
|
||||
|
||||
### Next.js App Router
|
||||
|
||||
Create `app/auth/[path]/page.tsx`:
|
||||
|
||||
```tsx
|
||||
import { AuthView } from "@neondatabase/auth/react/ui";
|
||||
import { authViewPaths } from "@neondatabase/auth/react/ui/server";
|
||||
|
||||
export function generateStaticParams() {
|
||||
return Object.values(authViewPaths).map((path) => ({ path }));
|
||||
}
|
||||
|
||||
export default async function AuthPage({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ path: string }>;
|
||||
}) {
|
||||
const { path } = await params;
|
||||
return <AuthView pathname={path} />;
|
||||
}
|
||||
```
|
||||
|
||||
### React SPA
|
||||
|
||||
```tsx
|
||||
import { Routes, Route, useParams } from "react-router-dom";
|
||||
import { AuthView } from "@neondatabase/auth/react/ui";
|
||||
|
||||
function AuthPage() {
|
||||
const { pathname } = useParams();
|
||||
return (
|
||||
<div className="flex min-h-screen items-center justify-center">
|
||||
<AuthView pathname={pathname} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export default function App() {
|
||||
return (
|
||||
<Routes>
|
||||
<Route path="/" element={<HomePage />} />
|
||||
<Route path="/auth/:pathname" element={<AuthPage />} />
|
||||
</Routes>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Available Auth Paths
|
||||
|
||||
| Path | Purpose |
|
||||
| ----------------- | ------------------------- |
|
||||
| `sign-in` | Sign in page |
|
||||
| `sign-up` | Sign up page |
|
||||
| `forgot-password` | Password reset request |
|
||||
| `reset-password` | Set new password |
|
||||
| `magic-link` | Magic link sign in |
|
||||
| `two-factor` | Two-factor authentication |
|
||||
| `callback` | OAuth callback (internal) |
|
||||
| `sign-out` | Sign out |
|
||||
|
||||
## SignedIn / SignedOut Components
|
||||
|
||||
Conditional rendering based on authentication state.
|
||||
|
||||
```tsx
|
||||
import { SignedIn, SignedOut, UserButton } from "@neondatabase/auth/react/ui";
|
||||
|
||||
function Navbar() {
|
||||
return (
|
||||
<nav>
|
||||
<SignedOut>
|
||||
<a href="/auth/sign-in">Sign In</a>
|
||||
<a href="/auth/sign-up">Sign Up</a>
|
||||
</SignedOut>
|
||||
<SignedIn>
|
||||
<UserButton />
|
||||
</SignedIn>
|
||||
</nav>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## UserButton Component
|
||||
|
||||
Displays user avatar with dropdown menu for account management.
|
||||
|
||||
```tsx
|
||||
import { UserButton } from "@neondatabase/auth/react/ui";
|
||||
|
||||
function Header() {
|
||||
return (
|
||||
<header>
|
||||
<h1>My App</h1>
|
||||
<UserButton />
|
||||
</header>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Social Login Configuration
|
||||
|
||||
**Important:** Social providers require TWO configurations:
|
||||
|
||||
1. **Enable in Neon Console** - Go to your project's Auth settings
|
||||
2. **Add to NeonAuthUIProvider** - Pass `social` prop
|
||||
|
||||
```tsx
|
||||
<NeonAuthUIProvider
|
||||
authClient={authClient}
|
||||
// ... other props
|
||||
social={{
|
||||
providers: ['google', 'github']
|
||||
}}
|
||||
>
|
||||
```
|
||||
|
||||
Without both configurations, social login buttons won't appear.
|
||||
158
neon-postgres/references/neon-cli.md
Normal file
158
neon-postgres/references/neon-cli.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Neon CLI
|
||||
|
||||
The Neon CLI is a command-line interface for managing Neon Serverless Postgres directly from your terminal. It provides the same capabilities as the Neon Platform API and is ideal for scripting, CI/CD pipelines, and developers who prefer terminal workflows.
|
||||
|
||||
## Installation
|
||||
|
||||
**macOS (Homebrew):**
|
||||
|
||||
```bash
|
||||
brew install neonctl
|
||||
```
|
||||
|
||||
**npm (cross-platform):**
|
||||
|
||||
```bash
|
||||
npm install -g neonctl
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
Authenticate with your Neon account:
|
||||
|
||||
```bash
|
||||
neonctl auth
|
||||
```
|
||||
|
||||
This opens a browser for OAuth authentication and stores credentials locally.
|
||||
|
||||
For CI/CD or non-interactive environments, use an API key:
|
||||
|
||||
```bash
|
||||
export NEON_API_KEY=your-api-key
|
||||
```
|
||||
|
||||
Get your API key from: https://console.neon.tech/app/settings/api-keys
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Project Management
|
||||
|
||||
```bash
|
||||
# List all projects
|
||||
neonctl projects list
|
||||
|
||||
# Create a new project
|
||||
neonctl projects create --name my-project
|
||||
|
||||
# Get project details
|
||||
neonctl projects get <project-id>
|
||||
|
||||
# Delete a project
|
||||
neonctl projects delete <project-id>
|
||||
```
|
||||
|
||||
### Branch Operations
|
||||
|
||||
```bash
|
||||
# List branches
|
||||
neonctl branches list --project-id <project-id>
|
||||
|
||||
# Create a branch
|
||||
neonctl branches create --project-id <project-id> --name dev
|
||||
|
||||
# Delete a branch
|
||||
neonctl branches delete <branch-id> --project-id <project-id>
|
||||
```
|
||||
|
||||
### Connection Strings
|
||||
|
||||
```bash
|
||||
# Get connection string
|
||||
neonctl connection-string --project-id <project-id>
|
||||
|
||||
# Get connection string for specific branch
|
||||
neonctl connection-string --project-id <project-id> --branch-id <branch-id>
|
||||
|
||||
# Get pooled connection string
|
||||
neonctl connection-string --project-id <project-id> --pooled
|
||||
```
|
||||
|
||||
### SQL Execution
|
||||
|
||||
```bash
|
||||
# Run SQL query
|
||||
neonctl sql "SELECT * FROM users LIMIT 10" --project-id <project-id>
|
||||
|
||||
# Run SQL from file
|
||||
neonctl sql --file schema.sql --project-id <project-id>
|
||||
```
|
||||
|
||||
### Database Management
|
||||
|
||||
```bash
|
||||
# List databases
|
||||
neonctl databases list --project-id <project-id> --branch-id <branch-id>
|
||||
|
||||
# Create database
|
||||
neonctl databases create --project-id <project-id> --name mydb
|
||||
|
||||
# List roles
|
||||
neonctl roles list --project-id <project-id> --branch-id <branch-id>
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
The CLI supports multiple output formats:
|
||||
|
||||
```bash
|
||||
# JSON output (default for scripting)
|
||||
neonctl projects list --output json
|
||||
|
||||
# Table output (human-readable)
|
||||
neonctl projects list --output table
|
||||
|
||||
# YAML output
|
||||
neonctl projects list --output yaml
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
Example GitHub Actions workflow:
|
||||
|
||||
```yaml
|
||||
- name: Create preview branch
|
||||
env:
|
||||
NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
|
||||
run: |
|
||||
neonctl branches create \
|
||||
--project-id ${{ vars.NEON_PROJECT_ID }} \
|
||||
--name preview-${{ github.event.pull_request.number }}
|
||||
```
|
||||
|
||||
## CLI vs MCP Server vs SDKs
|
||||
|
||||
| Tool | Best For |
|
||||
| -------------- | ------------------------------------------------- |
|
||||
| Neon CLI | Terminal workflows, scripts, CI/CD pipelines |
|
||||
| MCP Server | AI-assisted development with Claude, Cursor, etc. |
|
||||
| TypeScript SDK | Programmatic access in Node.js/TypeScript apps |
|
||||
| Python SDK | Programmatic access in Python applications |
|
||||
| REST API | Direct HTTP integration in any language |
|
||||
|
||||
## Documentation Resources
|
||||
|
||||
| Topic | URL |
|
||||
| -------------- | ------------------------------------------------------ |
|
||||
| CLI Reference | https://neon.com/docs/reference/neon-cli |
|
||||
| CLI Install | https://neon.com/docs/reference/cli-install |
|
||||
| CLI Auth | https://neon.com/docs/reference/cli-auth |
|
||||
| CLI Projects | https://neon.com/docs/reference/cli-projects |
|
||||
| CLI Branches | https://neon.com/docs/reference/cli-branches |
|
||||
| CLI Connection | https://neon.com/docs/reference/cli-connection-string |
|
||||
|
||||
Fetch CLI documentation:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/neon-cli
|
||||
```
|
||||
245
neon-postgres/references/neon-drizzle.md
Normal file
245
neon-postgres/references/neon-drizzle.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# Neon and Drizzle Integration
|
||||
|
||||
Integration patterns, configurations, and optimizations for using **Drizzle ORM** with **Neon** Postgres.
|
||||
|
||||
For official documentation:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/guides/drizzle
|
||||
```
|
||||
|
||||
## Choosing the Right Driver
|
||||
|
||||
Drizzle ORM works with multiple Postgres drivers. See `connection-methods.md` for the full decision tree.
|
||||
|
||||
| Platform | TCP Support | Pooling | Recommended Driver |
|
||||
| ----------------------- | ----------- | ------------------- | -------------------------- |
|
||||
| Vercel (Fluid) | Yes | `@vercel/functions` | `pg` (node-postgres) |
|
||||
| Cloudflare (Hyperdrive) | Yes | Hyperdrive | `pg` (node-postgres) |
|
||||
| Cloudflare Workers | No | No | `@neondatabase/serverless` |
|
||||
| Netlify Functions | No | No | `@neondatabase/serverless` |
|
||||
| Deno Deploy | No | No | `@neondatabase/serverless` |
|
||||
| Railway / Render | Yes | Built-in | `pg` (node-postgres) |
|
||||
|
||||
## Connection Setup
|
||||
|
||||
### 1. TCP with node-postgres (Long-Running Servers)
|
||||
|
||||
Best for Railway, Render, traditional VPS.
|
||||
|
||||
```bash
|
||||
npm install drizzle-orm pg
|
||||
npm install -D drizzle-kit @types/pg dotenv
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/db.ts
|
||||
import { drizzle } from "drizzle-orm/node-postgres";
|
||||
import { Pool } from "pg";
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
|
||||
export const db = drizzle({ client: pool });
|
||||
```
|
||||
|
||||
### 2. Vercel Fluid Compute with Connection Pooling
|
||||
|
||||
```bash
|
||||
npm install drizzle-orm pg @vercel/functions
|
||||
npm install -D drizzle-kit @types/pg
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/db.ts
|
||||
import { attachDatabasePool } from "@vercel/functions";
|
||||
import { drizzle } from "drizzle-orm/node-postgres";
|
||||
import { Pool } from "pg";
|
||||
import * as schema from "./schema";
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
|
||||
attachDatabasePool(pool);
|
||||
|
||||
export const db = drizzle({ client: pool, schema });
|
||||
```
|
||||
|
||||
### 3. HTTP Adapter (Edge Without TCP)
|
||||
|
||||
For Cloudflare Workers, Netlify Edge, Deno Deploy. Does NOT support interactive transactions.
|
||||
|
||||
```bash
|
||||
npm install drizzle-orm @neondatabase/serverless
|
||||
npm install -D drizzle-kit dotenv
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/db.ts
|
||||
import { drizzle } from "drizzle-orm/neon-http";
|
||||
import { neon } from "@neondatabase/serverless";
|
||||
|
||||
const sql = neon(process.env.DATABASE_URL!);
|
||||
export const db = drizzle(sql);
|
||||
```
|
||||
|
||||
### 4. WebSocket Adapter (Edge with Transactions)
|
||||
|
||||
```bash
|
||||
npm install drizzle-orm @neondatabase/serverless ws
|
||||
npm install -D drizzle-kit dotenv @types/ws
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/db.ts
|
||||
import { drizzle } from "drizzle-orm/neon-serverless";
|
||||
import { Pool, neonConfig } from "@neondatabase/serverless";
|
||||
import ws from "ws";
|
||||
|
||||
neonConfig.webSocketConstructor = ws; // Required for Node.js < v22
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
|
||||
export const db = drizzle(pool);
|
||||
```
|
||||
|
||||
## Drizzle Config
|
||||
|
||||
```typescript
|
||||
// drizzle.config.ts
|
||||
import { config } from "dotenv";
|
||||
import { defineConfig } from "drizzle-kit";
|
||||
|
||||
config({ path: ".env.local" });
|
||||
|
||||
export default defineConfig({
|
||||
schema: "./src/schema.ts",
|
||||
out: "./drizzle",
|
||||
dialect: "postgresql",
|
||||
dbCredentials: {
|
||||
url: process.env.DATABASE_URL!,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Migrations
|
||||
|
||||
```bash
|
||||
# Generate migrations
|
||||
npx drizzle-kit generate
|
||||
|
||||
# Apply migrations
|
||||
npx drizzle-kit migrate
|
||||
```
|
||||
|
||||
## Schema Definition
|
||||
|
||||
```typescript
|
||||
// src/schema.ts
|
||||
import { pgTable, serial, text, integer, timestamp } from "drizzle-orm/pg-core";
|
||||
|
||||
export const usersTable = pgTable("users", {
|
||||
id: serial("id").primaryKey(),
|
||||
name: text("name").notNull(),
|
||||
email: text("email").notNull().unique(),
|
||||
role: text("role").default("user").notNull(),
|
||||
createdAt: timestamp("created_at").defaultNow().notNull(),
|
||||
});
|
||||
|
||||
export type User = typeof usersTable.$inferSelect;
|
||||
export type NewUser = typeof usersTable.$inferInsert;
|
||||
|
||||
export const postsTable = pgTable("posts", {
|
||||
id: serial("id").primaryKey(),
|
||||
title: text("title").notNull(),
|
||||
content: text("content").notNull(),
|
||||
userId: integer("user_id")
|
||||
.notNull()
|
||||
.references(() => usersTable.id, { onDelete: "cascade" }),
|
||||
createdAt: timestamp("created_at").defaultNow().notNull(),
|
||||
});
|
||||
|
||||
export type Post = typeof postsTable.$inferSelect;
|
||||
export type NewPost = typeof postsTable.$inferInsert;
|
||||
```
|
||||
|
||||
## Query Patterns
|
||||
|
||||
### Batch Inserts
|
||||
|
||||
```typescript
|
||||
export async function batchInsertUsers(users: NewUser[]) {
|
||||
return db.insert(usersTable).values(users).returning();
|
||||
}
|
||||
```
|
||||
|
||||
### Prepared Statements
|
||||
|
||||
```typescript
|
||||
import { sql } from "drizzle-orm";
|
||||
|
||||
export const getUsersByRolePrepared = db
|
||||
.select()
|
||||
.from(usersTable)
|
||||
.where(sql`${usersTable.role} = $1`)
|
||||
.prepare("get_users_by_role");
|
||||
|
||||
// Usage: getUsersByRolePrepared.execute(['admin'])
|
||||
```
|
||||
|
||||
### Transactions
|
||||
|
||||
```typescript
|
||||
export async function createUserWithPosts(user: NewUser, posts: NewPost[]) {
|
||||
return await db.transaction(async (tx) => {
|
||||
const [newUser] = await tx.insert(usersTable).values(user).returning();
|
||||
|
||||
if (posts.length > 0) {
|
||||
await tx.insert(postsTable).values(
|
||||
posts.map((post) => ({
|
||||
...post,
|
||||
userId: newUser.id,
|
||||
})),
|
||||
);
|
||||
}
|
||||
|
||||
return newUser;
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Working with Neon Branches
|
||||
|
||||
```typescript
|
||||
import { drizzle } from "drizzle-orm/neon-http";
|
||||
import { neon } from "@neondatabase/serverless";
|
||||
|
||||
const getBranchUrl = () => {
|
||||
const env = process.env.NODE_ENV;
|
||||
if (env === "development") return process.env.DEV_DATABASE_URL;
|
||||
if (env === "test") return process.env.TEST_DATABASE_URL;
|
||||
return process.env.DATABASE_URL;
|
||||
};
|
||||
|
||||
const sql = neon(getBranchUrl()!);
|
||||
export const db = drizzle({ client: sql });
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```typescript
|
||||
export async function safeNeonOperation<T>(
|
||||
operation: () => Promise<T>,
|
||||
): Promise<T> {
|
||||
try {
|
||||
return await operation();
|
||||
} catch (error: any) {
|
||||
if (error.message?.includes("connection pool timeout")) {
|
||||
console.error("Neon connection pool timeout");
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Connection Management** - See `connection-methods.md` for platform-specific guidance
|
||||
2. **Neon Features** - Utilize branching for development/testing (see `features.md`)
|
||||
3. **Query Optimization** - Batch operations, use prepared statements
|
||||
4. **Schema Design** - Leverage Postgres-specific features, use appropriate indexes
|
||||
218
neon-postgres/references/neon-js.md
Normal file
218
neon-postgres/references/neon-js.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# Neon JS SDK
|
||||
|
||||
The `@neondatabase/neon-js` SDK provides a unified client for Neon Auth and Data API. It combines authentication handling with PostgREST-compatible database queries.
|
||||
|
||||
**Auth only?** Use `neon-auth.md` instead for smaller bundle size.
|
||||
|
||||
For official documentation:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/javascript-sdk
|
||||
```
|
||||
|
||||
## Package Selection
|
||||
|
||||
| Use Case | Package | Notes |
|
||||
| --------------- | ---------------------------- | ------------------- |
|
||||
| Auth + Data API | `@neondatabase/neon-js` | Full SDK |
|
||||
| Auth only | `@neondatabase/auth` | Smaller bundle |
|
||||
| Data API only | `@neondatabase/postgrest-js` | Bring your own auth |
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @neondatabase/neon-js
|
||||
```
|
||||
|
||||
## Quick Setup Patterns
|
||||
|
||||
### Next.js (Most Common)
|
||||
|
||||
**1. API Route Handler:**
|
||||
|
||||
```typescript
|
||||
// app/api/auth/[...path]/route.ts
|
||||
import { authApiHandler } from "@neondatabase/neon-js/auth/next";
|
||||
export const { GET, POST } = authApiHandler();
|
||||
```
|
||||
|
||||
**2. Auth Client:**
|
||||
|
||||
```typescript
|
||||
// lib/auth/client.ts
|
||||
import { createAuthClient } from "@neondatabase/neon-js/auth/next";
|
||||
export const authClient = createAuthClient();
|
||||
```
|
||||
|
||||
**3. Database Client:**
|
||||
|
||||
```typescript
|
||||
// lib/db/client.ts
|
||||
import { createClient } from "@neondatabase/neon-js";
|
||||
import type { Database } from "./database.types";
|
||||
|
||||
export const dbClient = createClient<Database>({
|
||||
auth: { url: process.env.NEXT_PUBLIC_NEON_AUTH_URL! },
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
### React SPA
|
||||
|
||||
```typescript
|
||||
import { createClient } from "@neondatabase/neon-js";
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react/adapters";
|
||||
|
||||
const client = createClient<Database>({
|
||||
auth: {
|
||||
adapter: BetterAuthReactAdapter(),
|
||||
url: import.meta.env.VITE_NEON_AUTH_URL,
|
||||
},
|
||||
dataApi: { url: import.meta.env.VITE_NEON_DATA_API_URL },
|
||||
});
|
||||
```
|
||||
|
||||
### Node.js Backend
|
||||
|
||||
```typescript
|
||||
import { createClient } from "@neondatabase/neon-js";
|
||||
|
||||
const client = createClient<Database>({
|
||||
auth: { url: process.env.NEON_AUTH_URL! },
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
# Next.js (.env.local)
|
||||
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
NEXT_PUBLIC_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
NEON_DATA_API_URL=https://ep-xxx.apirest.c-2.us-east-2.aws.neon.build/dbname/rest/v1
|
||||
|
||||
# Vite/React (.env)
|
||||
VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
VITE_NEON_DATA_API_URL=https://ep-xxx.apirest.c-2.us-east-2.aws.neon.build/dbname/rest/v1
|
||||
```
|
||||
|
||||
## Database Queries
|
||||
|
||||
All query methods follow PostgREST syntax (same as Supabase):
|
||||
|
||||
```typescript
|
||||
// Select with filters
|
||||
const { data } = await client
|
||||
.from("items")
|
||||
.select("id, name, status")
|
||||
.eq("status", "active")
|
||||
.order("created_at", { ascending: false })
|
||||
.limit(10);
|
||||
|
||||
// Insert
|
||||
const { data, error } = await client
|
||||
.from("items")
|
||||
.insert({ name: "New Item", status: "pending" })
|
||||
.select()
|
||||
.single();
|
||||
|
||||
// Update
|
||||
await client.from("items").update({ status: "completed" }).eq("id", 1);
|
||||
|
||||
// Delete
|
||||
await client.from("items").delete().eq("id", 1);
|
||||
```
|
||||
|
||||
For complete Data API query reference, see `neon-js/data-api.md`.
|
||||
|
||||
## Auth Methods
|
||||
|
||||
### BetterAuth API (Default)
|
||||
|
||||
```typescript
|
||||
// Sign in/up
|
||||
await client.auth.signIn.email({ email, password });
|
||||
await client.auth.signUp.email({ email, password, name });
|
||||
await client.auth.signOut();
|
||||
|
||||
// Get session
|
||||
const session = await client.auth.getSession();
|
||||
|
||||
// Social sign-in
|
||||
await client.auth.signIn.social({
|
||||
provider: "google",
|
||||
callbackURL: "/dashboard",
|
||||
});
|
||||
```
|
||||
|
||||
### Supabase-Compatible API
|
||||
|
||||
```typescript
|
||||
import { createClient, SupabaseAuthAdapter } from "@neondatabase/neon-js";
|
||||
|
||||
const client = createClient({
|
||||
auth: { adapter: SupabaseAuthAdapter(), url },
|
||||
dataApi: { url },
|
||||
});
|
||||
|
||||
await client.auth.signInWithPassword({ email, password });
|
||||
await client.auth.signUp({ email, password });
|
||||
const {
|
||||
data: { session },
|
||||
} = await client.auth.getSession();
|
||||
```
|
||||
|
||||
## Sub-Resources
|
||||
|
||||
| Topic | Resource |
|
||||
| ---------------- | ---------------------------- |
|
||||
| Data API queries | `neon-js/data-api.md` |
|
||||
| Common mistakes | `neon-js/common-mistakes.md` |
|
||||
|
||||
## Key Imports
|
||||
|
||||
```typescript
|
||||
// Main client
|
||||
import {
|
||||
createClient,
|
||||
SupabaseAuthAdapter,
|
||||
BetterAuthVanillaAdapter,
|
||||
} from "@neondatabase/neon-js";
|
||||
|
||||
// Next.js integration
|
||||
import {
|
||||
authApiHandler,
|
||||
createAuthClient,
|
||||
} from "@neondatabase/neon-js/auth/next";
|
||||
|
||||
// React adapter (NOT from main entry - must use subpath)
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react/adapters";
|
||||
|
||||
// UI components
|
||||
import {
|
||||
NeonAuthUIProvider,
|
||||
AuthView,
|
||||
SignInForm,
|
||||
} from "@neondatabase/neon-js/auth/react/ui";
|
||||
import { authViewPaths } from "@neondatabase/neon-js/auth/react/ui/server";
|
||||
|
||||
// CSS (choose one)
|
||||
import "@neondatabase/neon-js/ui/css"; // Without Tailwind
|
||||
// @import '@neondatabase/neon-js/ui/tailwind'; // With Tailwind v4 (in CSS file)
|
||||
```
|
||||
|
||||
## Generate Types
|
||||
|
||||
```bash
|
||||
npx neon-js gen-types --db-url "postgresql://..." --output src/types/database.ts
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
1. **Wrong adapter import**: Import `BetterAuthReactAdapter` from `auth/react/adapters` subpath
|
||||
2. **Forgetting to call adapter**: Use `SupabaseAuthAdapter()` with parentheses
|
||||
3. **Missing CSS import**: Import from `ui/css` or `ui/tailwind` (not both)
|
||||
4. **Wrong package for auth-only**: Use `@neondatabase/auth` for smaller bundle
|
||||
5. **Missing "use client"**: Required for auth client components
|
||||
|
||||
See `neon-js/common-mistakes.md` for detailed examples.
|
||||
127
neon-postgres/references/neon-js/common-mistakes.md
Normal file
127
neon-postgres/references/neon-js/common-mistakes.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Neon JS - Common Mistakes
|
||||
|
||||
Reference guide for common mistakes when using `@neondatabase/neon-js`.
|
||||
|
||||
## Import Mistakes
|
||||
|
||||
### BetterAuthReactAdapter Subpath Requirement
|
||||
|
||||
`BetterAuthReactAdapter` is **NOT** exported from the main package entry.
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```typescript
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/neon-js";
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```typescript
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react/adapters";
|
||||
```
|
||||
|
||||
### Adapter Factory Functions
|
||||
|
||||
All adapters must be called with `()`.
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```typescript
|
||||
const client = createClient({
|
||||
auth: {
|
||||
adapter: BetterAuthReactAdapter, // Missing ()
|
||||
url: process.env.NEON_AUTH_URL!,
|
||||
},
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```typescript
|
||||
const client = createClient({
|
||||
auth: {
|
||||
adapter: BetterAuthReactAdapter(), // Called as function
|
||||
url: process.env.NEON_AUTH_URL!,
|
||||
},
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS Import Mistakes
|
||||
|
||||
Choose **ONE** CSS import method:
|
||||
|
||||
**With Tailwind v4:**
|
||||
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
@import "@neondatabase/neon-js/ui/tailwind";
|
||||
```
|
||||
|
||||
**Without Tailwind:**
|
||||
|
||||
```typescript
|
||||
import "@neondatabase/neon-js/ui/css";
|
||||
```
|
||||
|
||||
**Never import both** - causes duplicate styles.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
**Required for Next.js:**
|
||||
|
||||
```bash
|
||||
# .env.local
|
||||
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
NEXT_PUBLIC_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
NEON_DATA_API_URL=https://ep-xxx.apirest.c-2.us-east-2.aws.neon.build/dbname/rest/v1
|
||||
```
|
||||
|
||||
**Required for Vite/React SPA:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
|
||||
VITE_NEON_DATA_API_URL=https://ep-xxx.apirest.c-2.us-east-2.aws.neon.build/dbname/rest/v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Mistakes
|
||||
|
||||
### Missing "use client" Directive
|
||||
|
||||
```typescript
|
||||
"use client"; // Required!
|
||||
|
||||
import { authClient } from "@/lib/auth/client";
|
||||
|
||||
function AuthStatus() {
|
||||
const session = authClient.useSession();
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Wrong API for Adapter
|
||||
|
||||
| Adapter | Sign In | Sign Up |
|
||||
| ---------------------- | ----------------------------------------- | ----------------------------------- |
|
||||
| BetterAuthReactAdapter | `signIn.email({ email, password })` | `signUp.email({ email, password })` |
|
||||
| SupabaseAuthAdapter | `signInWithPassword({ email, password })` | `signUp({ email, password })` |
|
||||
|
||||
### Using neon-js for Auth Only
|
||||
|
||||
If you only need auth (no database queries), use `@neondatabase/auth` for smaller bundle size:
|
||||
|
||||
```bash
|
||||
# Auth only - smaller bundle
|
||||
npm install @neondatabase/auth
|
||||
|
||||
# Auth + Data API - full SDK
|
||||
npm install @neondatabase/neon-js
|
||||
```
|
||||
481
neon-postgres/references/neon-js/data-api.md
Normal file
481
neon-postgres/references/neon-js/data-api.md
Normal file
@@ -0,0 +1,481 @@
|
||||
# Neon JS Data API Reference
|
||||
|
||||
Complete reference for PostgREST-style database queries using `@neondatabase/neon-js`.
|
||||
|
||||
## Client Setup
|
||||
|
||||
### Next.js
|
||||
|
||||
```typescript
|
||||
// lib/db/client.ts
|
||||
import { createClient } from "@neondatabase/neon-js";
|
||||
import type { Database } from "./database.types";
|
||||
|
||||
export const dbClient = createClient<Database>({
|
||||
auth: { url: process.env.NEXT_PUBLIC_NEON_AUTH_URL! },
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
### React SPA
|
||||
|
||||
```typescript
|
||||
import { createClient } from "@neondatabase/neon-js";
|
||||
import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react/adapters";
|
||||
|
||||
const client = createClient<Database>({
|
||||
auth: {
|
||||
adapter: BetterAuthReactAdapter(),
|
||||
url: import.meta.env.VITE_NEON_AUTH_URL,
|
||||
},
|
||||
dataApi: { url: import.meta.env.VITE_NEON_DATA_API_URL },
|
||||
});
|
||||
```
|
||||
|
||||
### Node.js Backend
|
||||
|
||||
```typescript
|
||||
import { createClient } from "@neondatabase/neon-js";
|
||||
|
||||
const client = createClient<Database>({
|
||||
auth: { url: process.env.NEON_AUTH_URL! },
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Query Patterns
|
||||
|
||||
All query methods follow PostgREST syntax (same as Supabase).
|
||||
|
||||
### Select Queries
|
||||
|
||||
**Basic select:**
|
||||
|
||||
```typescript
|
||||
const { data, error } = await client.from("items").select();
|
||||
```
|
||||
|
||||
**Select specific columns:**
|
||||
|
||||
```typescript
|
||||
const { data } = await client.from("items").select("id, name, status");
|
||||
```
|
||||
|
||||
**Select with filters:**
|
||||
|
||||
```typescript
|
||||
const { data } = await client
|
||||
.from("items")
|
||||
.select("id, name, status")
|
||||
.eq("status", "active")
|
||||
.order("created_at", { ascending: false })
|
||||
.limit(10);
|
||||
```
|
||||
|
||||
**Select single row:**
|
||||
|
||||
```typescript
|
||||
const { data, error } = await client
|
||||
.from("items")
|
||||
.select("*")
|
||||
.eq("id", 1)
|
||||
.single();
|
||||
```
|
||||
|
||||
### Insert
|
||||
|
||||
**Insert single row:**
|
||||
|
||||
```typescript
|
||||
const { data, error } = await client
|
||||
.from("items")
|
||||
.insert({ name: "New Item", status: "pending" })
|
||||
.select()
|
||||
.single();
|
||||
```
|
||||
|
||||
**Insert multiple rows:**
|
||||
|
||||
```typescript
|
||||
const { data, error } = await client
|
||||
.from("items")
|
||||
.insert([
|
||||
{ name: "Item 1", status: "pending" },
|
||||
{ name: "Item 2", status: "pending" },
|
||||
])
|
||||
.select();
|
||||
```
|
||||
|
||||
### Update
|
||||
|
||||
**Update with filter:**
|
||||
|
||||
```typescript
|
||||
await client.from("items").update({ status: "completed" }).eq("id", 1);
|
||||
```
|
||||
|
||||
**Update and return data:**
|
||||
|
||||
```typescript
|
||||
const { data, error } = await client
|
||||
.from("items")
|
||||
.update({ status: "completed" })
|
||||
.eq("id", 1)
|
||||
.select()
|
||||
.single();
|
||||
```
|
||||
|
||||
### Delete
|
||||
|
||||
**Delete single row:**
|
||||
|
||||
```typescript
|
||||
await client.from("items").delete().eq("id", 1);
|
||||
```
|
||||
|
||||
**Delete and return data:**
|
||||
|
||||
```typescript
|
||||
const { data, error } = await client
|
||||
.from("items")
|
||||
.delete()
|
||||
.eq("id", 1)
|
||||
.select()
|
||||
.single();
|
||||
```
|
||||
|
||||
### Upsert
|
||||
|
||||
```typescript
|
||||
await client
|
||||
.from("items")
|
||||
.upsert({ id: 1, name: "Updated Item", status: "active" });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Filtering
|
||||
|
||||
### Comparison Operators
|
||||
|
||||
```typescript
|
||||
// Equal
|
||||
.eq("status", "active")
|
||||
|
||||
// Not equal
|
||||
.neq("status", "archived")
|
||||
|
||||
// Greater than
|
||||
.gt("price", 100)
|
||||
|
||||
// Greater than or equal
|
||||
.gte("price", 100)
|
||||
|
||||
// Less than
|
||||
.lt("price", 100)
|
||||
|
||||
// Less than or equal
|
||||
.lte("price", 100)
|
||||
|
||||
// Like (pattern matching)
|
||||
.like("name", "%item%")
|
||||
|
||||
// ILike (case-insensitive)
|
||||
.ilike("name", "%item%")
|
||||
|
||||
// Is null
|
||||
.is("deleted_at", null)
|
||||
|
||||
// Is not null
|
||||
.not("deleted_at", "is", null)
|
||||
|
||||
// In array
|
||||
.in("status", ["active", "pending"])
|
||||
|
||||
// Contains (for arrays/JSONB)
|
||||
.contains("tags", ["important"])
|
||||
```
|
||||
|
||||
### Logical Operators
|
||||
|
||||
```typescript
|
||||
// AND (chained)
|
||||
.eq("status", "active")
|
||||
.gt("price", 100)
|
||||
|
||||
// OR
|
||||
.or("status.eq.active,price.gt.100")
|
||||
|
||||
// NOT
|
||||
.not("status", "eq", "archived")
|
||||
```
|
||||
|
||||
### Ordering
|
||||
|
||||
```typescript
|
||||
// Ascending
|
||||
.order("created_at", { ascending: true })
|
||||
|
||||
// Descending
|
||||
.order("created_at", { ascending: false })
|
||||
|
||||
// Multiple columns
|
||||
.order("status", { ascending: true })
|
||||
.order("created_at", { ascending: false })
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
```typescript
|
||||
// Limit
|
||||
.limit(10)
|
||||
|
||||
// Range (offset + limit)
|
||||
.range(0, 9) // First 10 items
|
||||
|
||||
// Range for pagination
|
||||
const page = 1;
|
||||
const pageSize = 10;
|
||||
.range((page - 1) * pageSize, page * pageSize - 1)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Relationships
|
||||
|
||||
### Select with Relationships
|
||||
|
||||
**One-to-many:**
|
||||
|
||||
```typescript
|
||||
const { data } = await client
|
||||
.from("posts")
|
||||
.select("id, title, author:users(name, email)");
|
||||
```
|
||||
|
||||
**Many-to-many:**
|
||||
|
||||
```typescript
|
||||
const { data } = await client
|
||||
.from("posts")
|
||||
.select("id, title, tags:post_tags(tag:tags(name))");
|
||||
```
|
||||
|
||||
**Nested relationships:**
|
||||
|
||||
```typescript
|
||||
const { data } = await client.from("posts").select(`
|
||||
id,
|
||||
title,
|
||||
author:users(
|
||||
id,
|
||||
name,
|
||||
profile:profiles(bio, avatar)
|
||||
)
|
||||
`);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type Generation
|
||||
|
||||
Generate TypeScript types from your database schema:
|
||||
|
||||
```bash
|
||||
npx neon-js gen-types --db-url "postgresql://user:pass@host/db" --output src/types/database.ts
|
||||
```
|
||||
|
||||
Or using environment variable:
|
||||
|
||||
```bash
|
||||
npx neon-js gen-types --db-url "$DATABASE_URL" --output lib/db/database.types.ts
|
||||
```
|
||||
|
||||
**Use types in client:**
|
||||
|
||||
```typescript
|
||||
import { createClient } from "@neondatabase/neon-js";
|
||||
import type { Database } from "./database.types";
|
||||
|
||||
export const dbClient = createClient<Database>({
|
||||
auth: { url: process.env.NEXT_PUBLIC_NEON_AUTH_URL! },
|
||||
dataApi: { url: process.env.NEON_DATA_API_URL! },
|
||||
});
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Full TypeScript autocomplete for tables and columns
|
||||
- Type-safe queries
|
||||
- Compile-time error checking
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Check for errors:**
|
||||
|
||||
```typescript
|
||||
const { data, error } = await client.from("items").select();
|
||||
|
||||
if (error) {
|
||||
console.error("Database error:", error.message);
|
||||
console.error("Error code:", error.code);
|
||||
console.error("Error details:", error.details);
|
||||
return;
|
||||
}
|
||||
|
||||
// Use data
|
||||
console.log(data);
|
||||
```
|
||||
|
||||
**Common error codes:**
|
||||
|
||||
- `PGRST116` - No rows returned (when using `.single()`)
|
||||
- `23505` - Unique violation
|
||||
- `23503` - Foreign key violation
|
||||
- `42P01` - Table does not exist
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Server Component (Next.js)
|
||||
|
||||
```typescript
|
||||
// app/posts/page.tsx
|
||||
import { dbClient } from "@/lib/db/client";
|
||||
|
||||
export default async function PostsPage() {
|
||||
const { data: posts, error } = await dbClient
|
||||
.from("posts")
|
||||
.select("id, title, created_at, author:users(name)")
|
||||
.order("created_at", { ascending: false })
|
||||
.limit(10);
|
||||
|
||||
if (error) return <div>Error loading posts</div>;
|
||||
|
||||
return (
|
||||
<ul>
|
||||
{posts?.map((post) => (
|
||||
<li key={post.id}>
|
||||
<h2>{post.title}</h2>
|
||||
<p>By {post.author?.name}</p>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### API Route (Next.js)
|
||||
|
||||
```typescript
|
||||
// app/api/posts/route.ts
|
||||
import { dbClient } from "@/lib/db/client";
|
||||
import { NextResponse } from "next/server";
|
||||
|
||||
export async function GET() {
|
||||
const { data, error } = await dbClient.from("posts").select();
|
||||
|
||||
if (error) {
|
||||
return NextResponse.json({ error: error.message }, { status: 500 });
|
||||
}
|
||||
|
||||
return NextResponse.json(data);
|
||||
}
|
||||
|
||||
export async function POST(request: Request) {
|
||||
const body = await request.json();
|
||||
|
||||
const { data, error } = await dbClient
|
||||
.from("posts")
|
||||
.insert(body)
|
||||
.select()
|
||||
.single();
|
||||
|
||||
if (error) {
|
||||
return NextResponse.json({ error: error.message }, { status: 400 });
|
||||
}
|
||||
|
||||
return NextResponse.json(data, { status: 201 });
|
||||
}
|
||||
```
|
||||
|
||||
### Client Component (React)
|
||||
|
||||
```typescript
|
||||
"use client";
|
||||
|
||||
import { useEffect, useState } from "react";
|
||||
import { dbClient } from "@/lib/db/client";
|
||||
|
||||
export function ItemsList() {
|
||||
const [items, setItems] = useState([]);
|
||||
const [loading, setLoading] = useState(true);
|
||||
|
||||
useEffect(() => {
|
||||
async function fetchItems() {
|
||||
const { data, error } = await dbClient
|
||||
.from("items")
|
||||
.select("id, name, status")
|
||||
.eq("status", "active");
|
||||
|
||||
if (error) {
|
||||
console.error(error);
|
||||
return;
|
||||
}
|
||||
|
||||
setItems(data || []);
|
||||
setLoading(false);
|
||||
}
|
||||
|
||||
fetchItems();
|
||||
}, []);
|
||||
|
||||
if (loading) return <div>Loading...</div>;
|
||||
|
||||
return (
|
||||
<ul>
|
||||
{items.map((item) => (
|
||||
<li key={item.id}>{item.name}</li>
|
||||
))}
|
||||
</ul>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Supabase Migration
|
||||
|
||||
The Neon JS SDK uses the same PostgREST API as Supabase, making migration straightforward:
|
||||
|
||||
**Before (Supabase):**
|
||||
|
||||
```typescript
|
||||
import { createClient } from "@supabase/supabase-js";
|
||||
|
||||
const client = createClient(SUPABASE_URL, SUPABASE_KEY);
|
||||
```
|
||||
|
||||
**After (Neon):**
|
||||
|
||||
```typescript
|
||||
import { createClient, SupabaseAuthAdapter } from "@neondatabase/neon-js";
|
||||
|
||||
const client = createClient({
|
||||
auth: { adapter: SupabaseAuthAdapter(), url: NEON_AUTH_URL },
|
||||
dataApi: { url: NEON_DATA_API_URL },
|
||||
});
|
||||
```
|
||||
|
||||
**Query syntax remains the same:**
|
||||
|
||||
```typescript
|
||||
// Works identically in both
|
||||
await client.auth.signInWithPassword({ email, password });
|
||||
const { data } = await client.from("items").select();
|
||||
```
|
||||
96
neon-postgres/references/neon-platform-api.md
Normal file
96
neon-postgres/references/neon-platform-api.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Neon Platform API
|
||||
|
||||
The Neon Platform API allows you to manage Neon projects, branches, databases, and resources programmatically. You can use the REST API directly or through official SDKs.
|
||||
|
||||
## Options
|
||||
|
||||
| Method | Package/URL | Best For |
|
||||
| -------------- | ----------------------------------- | ------------------------------- |
|
||||
| REST API | `https://console.neon.tech/api/v2/` | Any language, direct HTTP calls |
|
||||
| TypeScript SDK | `@neondatabase/api-client` | Node.js, TypeScript projects |
|
||||
| Python SDK | `neon-api` | Python scripts and applications |
|
||||
| CLI | `neonctl` | Terminal-based management |
|
||||
|
||||
## Documentation
|
||||
|
||||
```bash
|
||||
# REST API documentation
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/api-reference
|
||||
|
||||
# TypeScript SDK
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/typescript-sdk
|
||||
|
||||
# Python SDK
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/python-sdk
|
||||
|
||||
# CLI
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/neon-cli
|
||||
```
|
||||
|
||||
For the interactive API reference: https://api-docs.neon.tech/reference/getting-started-with-neon-api
|
||||
|
||||
## Sub-Resources
|
||||
|
||||
For detailed information, reference the appropriate sub-resource:
|
||||
|
||||
### REST API Details
|
||||
|
||||
| Topic | Resource |
|
||||
| ----------------------------- | -------------------------------- |
|
||||
| Guidelines, Auth, Rate Limits | `neon-rest-api/guidelines.md` |
|
||||
| Projects | `neon-rest-api/projects.md` |
|
||||
| Branches, Databases, Roles | `neon-rest-api/branches.md` |
|
||||
| Compute Endpoints | `neon-rest-api/endpoints.md` |
|
||||
| API Keys | `neon-rest-api/keys.md` |
|
||||
| Operations | `neon-rest-api/operations.md` |
|
||||
| Organizations | `neon-rest-api/organizations.md` |
|
||||
|
||||
### SDKs
|
||||
|
||||
| Language | Resource |
|
||||
| ---------- | ------------------------ |
|
||||
| TypeScript | `neon-typescript-sdk.md` |
|
||||
| Python | `neon-python-sdk.md` |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Authentication
|
||||
|
||||
All API requests require a Neon API key:
|
||||
|
||||
```bash
|
||||
Authorization: Bearer $NEON_API_KEY
|
||||
```
|
||||
|
||||
### API Key Types
|
||||
|
||||
| Type | Scope | Best For |
|
||||
| -------------- | ------------------------------- | ----------------------------- |
|
||||
| Personal | All projects user has access to | Individual use, scripting |
|
||||
| Organization | Entire organization | CI/CD, org-wide automation |
|
||||
| Project-scoped | Single project only | Project-specific integrations |
|
||||
|
||||
### Rate Limits
|
||||
|
||||
- 700 requests per minute (~11 per second)
|
||||
- Bursts up to 40 requests per second per route
|
||||
- Handle `429 Too Many Requests` with retry/backoff
|
||||
|
||||
## Common Operations Quick Reference
|
||||
|
||||
| Operation | REST API | TypeScript SDK | Python SDK |
|
||||
| ------------------ | ------------------------------------------ | --------------------------- | --------------------- |
|
||||
| List Projects | `GET /projects` | `listProjects({})` | `projects()` |
|
||||
| Create Project | `POST /projects` | `createProject({...})` | `project_create(...)` |
|
||||
| Get Connection URI | `GET /projects/{id}/connection_uri` | `getConnectionUri({...})` | `connection_uri(...)` |
|
||||
| Create Branch | `POST /projects/{id}/branches` | `createProjectBranch(...)` | `branch_create(...)` |
|
||||
| Start Endpoint | `POST /projects/{id}/endpoints/{id}/start` | `startProjectEndpoint(...)` | `endpoint_start(...)` |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Status | Meaning | Action |
|
||||
| ------ | ------------ | ---------------------------- |
|
||||
| 401 | Unauthorized | Check API key |
|
||||
| 404 | Not Found | Verify resource ID |
|
||||
| 429 | Rate Limited | Implement retry with backoff |
|
||||
| 500 | Server Error | Retry or contact support |
|
||||
261
neon-postgres/references/neon-python-sdk.md
Normal file
261
neon-postgres/references/neon-python-sdk.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# Neon Python SDK
|
||||
|
||||
The `neon-api` Python SDK is a Pythonic wrapper around the Neon REST API. It provides methods for managing all Neon resources, including projects, branches, endpoints, roles, and databases.
|
||||
|
||||
For core concepts (Organization, Project, Branch, Endpoint, etc.), see `what-is-neon.md`.
|
||||
|
||||
## Documentation
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/python-sdk
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install neon-api
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
```python
|
||||
import os
|
||||
from neon_api import NeonAPI
|
||||
|
||||
api_key = os.getenv("NEON_API_KEY")
|
||||
if not api_key:
|
||||
raise ValueError("NEON_API_KEY environment variable is not set.")
|
||||
|
||||
neon = NeonAPI(api_key=api_key)
|
||||
```
|
||||
|
||||
## Projects
|
||||
|
||||
### List Projects
|
||||
|
||||
```python
|
||||
all_projects = neon.projects()
|
||||
```
|
||||
|
||||
### Create Project
|
||||
|
||||
```python
|
||||
new_project = neon.project_create(
|
||||
project={
|
||||
'name': 'my-new-project',
|
||||
'pg_version': 17
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Get Project Details
|
||||
|
||||
```python
|
||||
project = neon.project(project_id='your-project-id')
|
||||
```
|
||||
|
||||
### Update Project
|
||||
|
||||
```python
|
||||
neon.project_update(
|
||||
project_id='your-project-id',
|
||||
project={
|
||||
'name': 'renamed-project',
|
||||
'default_endpoint_settings': {
|
||||
'autoscaling_limit_min_cu': 1,
|
||||
'autoscaling_limit_max_cu': 2,
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Delete Project
|
||||
|
||||
```python
|
||||
neon.project_delete(project_id='project-to-delete')
|
||||
```
|
||||
|
||||
### Get Connection URI
|
||||
|
||||
```python
|
||||
uri = neon.connection_uri(
|
||||
project_id='your-project-id',
|
||||
database_name='neondb',
|
||||
role_name='neondb_owner'
|
||||
)
|
||||
print(f"Connection URI: {uri.uri}")
|
||||
```
|
||||
|
||||
## Branches
|
||||
|
||||
### Create Branch
|
||||
|
||||
```python
|
||||
new_branch = neon.branch_create(
|
||||
project_id='your-project-id',
|
||||
branch={'name': 'feature-branch'},
|
||||
endpoints=[
|
||||
{'type': 'read_write', 'autoscaling_limit_max_cu': 1}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### List Branches
|
||||
|
||||
```python
|
||||
branches = neon.branches(project_id='your-project-id')
|
||||
```
|
||||
|
||||
### Get Branch Details
|
||||
|
||||
```python
|
||||
branch = neon.branch(project_id='your-project-id', branch_id='br-xxx')
|
||||
```
|
||||
|
||||
### Update Branch
|
||||
|
||||
```python
|
||||
neon.branch_update(
|
||||
project_id='your-project-id',
|
||||
branch_id='br-xxx',
|
||||
branch={'name': 'updated-branch-name'}
|
||||
)
|
||||
```
|
||||
|
||||
### Delete Branch
|
||||
|
||||
```python
|
||||
neon.branch_delete(project_id='your-project-id', branch_id='br-xxx')
|
||||
```
|
||||
|
||||
## Databases
|
||||
|
||||
### Create Database
|
||||
|
||||
```python
|
||||
neon.database_create(
|
||||
project_id='your-project-id',
|
||||
branch_id='br-xxx',
|
||||
database={'name': 'my-app-db', 'owner_name': 'neondb_owner'}
|
||||
)
|
||||
```
|
||||
|
||||
### List Databases
|
||||
|
||||
```python
|
||||
databases = neon.databases(project_id='your-project-id', branch_id='br-xxx')
|
||||
```
|
||||
|
||||
### Delete Database
|
||||
|
||||
```python
|
||||
neon.database_delete(
|
||||
project_id='your-project-id',
|
||||
branch_id='br-xxx',
|
||||
database_id='my-app-db'
|
||||
)
|
||||
```
|
||||
|
||||
## Roles
|
||||
|
||||
### Create Role
|
||||
|
||||
```python
|
||||
new_role = neon.role_create(
|
||||
project_id='your-project-id',
|
||||
branch_id='br-xxx',
|
||||
role_name='app_user'
|
||||
)
|
||||
print(f"Password: {new_role.role.password}")
|
||||
```
|
||||
|
||||
### List Roles
|
||||
|
||||
```python
|
||||
roles = neon.roles(project_id='your-project-id', branch_id='br-xxx')
|
||||
```
|
||||
|
||||
### Delete Role
|
||||
|
||||
```python
|
||||
neon.role_delete(
|
||||
project_id='your-project-id',
|
||||
branch_id='br-xxx',
|
||||
role_name='app_user'
|
||||
)
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Create Endpoint
|
||||
|
||||
```python
|
||||
neon.endpoint_create(
|
||||
project_id='your-project-id',
|
||||
endpoint={
|
||||
'branch_id': 'br-xxx',
|
||||
'type': 'read_only'
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Start/Suspend Endpoint
|
||||
|
||||
```python
|
||||
# Start
|
||||
neon.endpoint_start(project_id='your-project-id', endpoint_id='ep-xxx')
|
||||
|
||||
# Suspend
|
||||
neon.endpoint_suspend(project_id='your-project-id', endpoint_id='ep-xxx')
|
||||
```
|
||||
|
||||
### Update Endpoint
|
||||
|
||||
```python
|
||||
neon.endpoint_update(
|
||||
project_id='your-project-id',
|
||||
endpoint_id='ep-xxx',
|
||||
endpoint={'autoscaling_limit_max_cu': 2}
|
||||
)
|
||||
```
|
||||
|
||||
### Delete Endpoint
|
||||
|
||||
```python
|
||||
neon.endpoint_delete(project_id='your-project-id', endpoint_id='ep-xxx')
|
||||
```
|
||||
|
||||
## API Keys
|
||||
|
||||
### List API Keys
|
||||
|
||||
```python
|
||||
api_keys = neon.api_keys()
|
||||
```
|
||||
|
||||
### Create API Key
|
||||
|
||||
```python
|
||||
new_key = neon.api_key_create(key_name='my-script-key')
|
||||
print(f"Key (store securely!): {new_key.key}")
|
||||
```
|
||||
|
||||
### Revoke API Key
|
||||
|
||||
```python
|
||||
neon.api_key_revoke(1234) # key ID
|
||||
```
|
||||
|
||||
## Operations
|
||||
|
||||
### List Operations
|
||||
|
||||
```python
|
||||
ops = neon.operations(project_id='your-project-id')
|
||||
```
|
||||
|
||||
### Get Operation Details
|
||||
|
||||
```python
|
||||
op = neon.operation(project_id='your-project-id', operation_id='op-xxx')
|
||||
```
|
||||
552
neon-postgres/references/neon-rest-api/branches.md
Normal file
552
neon-postgres/references/neon-rest-api/branches.md
Normal file
@@ -0,0 +1,552 @@
|
||||
## Overview
|
||||
|
||||
This document outlines the rules for managing branches in a Neon project using the Neon API.
|
||||
|
||||
## Manage branches
|
||||
|
||||
### Create branch
|
||||
|
||||
1. Action: Creates a new branch within a specified project. By default, a branch is created from the project's default branch, but you can specify a parent branch, a point-in-time (LSN or timestamp), and attach compute endpoints.
|
||||
2. Endpoint: `POST /projects/{project_id}/branches`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project where the branch will be created.
|
||||
4. Body Parameters: The request body is optional. If provided, it can contain `endpoints` and/or `branch` objects.
|
||||
|
||||
`endpoints` (array of objects, optional): A list of compute endpoints to create and attach to the new branch.
|
||||
- `type` (string, required): The endpoint type. Allowed values: `read_write`, `read_only`.
|
||||
- `autoscaling_limit_min_cu` (number, optional): The minimum number of Compute Units (CU). Minimum value is `0.25`.
|
||||
- `autoscaling_limit_max_cu` (number, optional): The maximum number of Compute Units (CU). Minimum value is `0.25`.
|
||||
- `provisioner` (string, optional): The compute provisioner. Specify `k8s-neonvm` to enable Autoscaling. Allowed values: `k8s-pod`, `k8s-neonvm`.
|
||||
- `suspend_timeout_seconds` (integer, optional): Duration of inactivity in seconds before a compute is suspended. Ranges from -1 (never suspend) to 604800 (1 week). A value of `0` uses the default of 300 seconds (5 minutes).
|
||||
|
||||
`branch` (object, optional): Specifies the properties of the new branch.
|
||||
- `name` (string, optional): A name for the branch (max 256 characters). If omitted, a name is auto-generated.
|
||||
- `parent_id` (string, optional): The ID of the parent branch. If omitted, the project's default branch is used as the parent.
|
||||
- `parent_lsn` (string, optional): A Log Sequence Number (LSN) from the parent branch to create the new branch from a specific point-in-time.
|
||||
- `parent_timestamp` (string, optional): An ISO 8601 timestamp (e.g., `2025-08-26T12:00:00Z`) to create the branch from a specific point-in-time.
|
||||
- `protected` (boolean, optional): If `true`, the branch is created as a protected branch.
|
||||
- `init_source` (string, optional): The source for branch initialization. `parent-data` (default) copies schema and data. `schema-only` creates a new root branch with only the schema from the specified parent.
|
||||
- `expires_at` (string, optional): An RFC 3339 timestamp for when the branch should be automatically deleted (e.g., `2025-06-09T18:02:16Z`).
|
||||
|
||||
Example: Create a branch from a specific parent with a read-write compute
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/branches' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"endpoints": [
|
||||
{
|
||||
"type": "read_write"
|
||||
}
|
||||
],
|
||||
"branch": {
|
||||
"parent_id": "br-super-wildflower-adniii9u",
|
||||
"name": "my-new-feature-branch"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"branch": {
|
||||
"id": "br-damp-glitter-adqd4hk5",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"parent_id": "br-super-wildflower-adniii9u",
|
||||
"parent_lsn": "0/1A7F730",
|
||||
"name": "my-new-feature-branch",
|
||||
"current_state": "init",
|
||||
"pending_state": "ready",
|
||||
"state_changed_at": "2025-09-10T16:45:52Z",
|
||||
"creation_source": "console",
|
||||
"primary": false,
|
||||
"default": false,
|
||||
"protected": false,
|
||||
"cpu_used_sec": 0,
|
||||
"compute_time_seconds": 0,
|
||||
"active_time_seconds": 0,
|
||||
"written_data_bytes": 0,
|
||||
"data_transfer_bytes": 0,
|
||||
"created_at": "2025-09-10T16:45:52Z",
|
||||
"updated_at": "2025-09-10T16:45:52Z",
|
||||
"created_by": {
|
||||
"name": "<USER_NAME>",
|
||||
"image": "<USER_IMAGE_URL>"
|
||||
},
|
||||
"init_source": "parent-data"
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"host": "ep-raspy-glade-ad8e3gvy.c-2.us-east-1.aws.neon.tech",
|
||||
"id": "ep-raspy-glade-ad8e3gvy",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-damp-glitter-adqd4hk5",
|
||||
"autoscaling_limit_min_cu": 0.25,
|
||||
"autoscaling_limit_max_cu": 2,
|
||||
"region_id": "aws-us-east-1",
|
||||
"type": "read_write",
|
||||
"current_state": "init",
|
||||
"pending_state": "active",
|
||||
"settings": {},
|
||||
"pooler_enabled": false,
|
||||
"pooler_mode": "transaction",
|
||||
"disabled": false,
|
||||
"passwordless_access": true,
|
||||
"creation_source": "console",
|
||||
"created_at": "2025-09-10T16:45:52Z",
|
||||
"updated_at": "2025-09-10T16:45:52Z",
|
||||
"proxy_host": "c-2.us-east-1.aws.neon.tech",
|
||||
"suspend_timeout_seconds": 0,
|
||||
"provisioner": "k8s-neonvm"
|
||||
}
|
||||
],
|
||||
"operations": [
|
||||
{
|
||||
"id": "cf5d0923-fc13-4125-83d5-8fc31c6b0214",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-damp-glitter-adqd4hk5",
|
||||
"action": "create_branch",
|
||||
"status": "running",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T16:45:52Z",
|
||||
"updated_at": "2025-09-10T16:45:52Z",
|
||||
"total_duration_ms": 0
|
||||
},
|
||||
{
|
||||
"id": "e3c60b62-00c8-4ad4-9cd1-cdc3e8fd8154",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-damp-glitter-adqd4hk5",
|
||||
"endpoint_id": "ep-raspy-glade-ad8e3gvy",
|
||||
"action": "start_compute",
|
||||
"status": "scheduling",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T16:45:52Z",
|
||||
"updated_at": "2025-09-10T16:45:52Z",
|
||||
"total_duration_ms": 0
|
||||
}
|
||||
],
|
||||
"roles": [
|
||||
{
|
||||
"branch_id": "br-damp-glitter-adqd4hk5",
|
||||
"name": "neondb_owner",
|
||||
"protected": false,
|
||||
"created_at": "2025-09-10T12:14:58Z",
|
||||
"updated_at": "2025-09-10T12:14:58Z"
|
||||
}
|
||||
],
|
||||
"databases": [
|
||||
{
|
||||
"id": 9554148,
|
||||
"branch_id": "br-damp-glitter-adqd4hk5",
|
||||
"name": "neondb",
|
||||
"owner_name": "neondb_owner",
|
||||
"created_at": "2025-09-10T12:14:58Z",
|
||||
"updated_at": "2025-09-10T12:14:58Z"
|
||||
}
|
||||
],
|
||||
"connection_uris": [
|
||||
{
|
||||
"connection_uri": "postgresql://neondb_owner:npg_EwcS9IOgFfb7@ep-raspy-glade-ad8e3gvy.c-2.us-east-1.aws.neon.tech/neondb?sslmode=require",
|
||||
"connection_parameters": {
|
||||
"database": "neondb",
|
||||
"password": "npg_EwcS9IOgFfb7",
|
||||
"role": "neondb_owner",
|
||||
"host": "ep-raspy-glade-ad8e3gvy.c-2.us-east-1.aws.neon.tech",
|
||||
"pooler_host": "ep-raspy-glade-ad8e3gvy-pooler.c-2.us-east-1.aws.neon.tech"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### List branches
|
||||
|
||||
1. Action: Retrieves a list of branches for the specified project. Supports filtering, sorting, and pagination.
|
||||
2. Endpoint: `GET /projects/{project_id}/branches`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
4. Query Parameters:
|
||||
- `search` (string, optional): Filters branches by a partial match on name or ID.
|
||||
- `sort_by` (string, optional): The field to sort by. Allowed values: `name`, `created_at`, `updated_at`. Defaults to `updated_at`.
|
||||
- `sort_order` (string, optional): The sort order. Allowed values: `asc`, `desc`. Defaults to `desc`.
|
||||
- `limit` (integer, optional): The number of branches to return (1 to 10000).
|
||||
- `cursor` (string, optional): The cursor from a previous response for pagination.
|
||||
|
||||
Example: List all branches sorted by creation date
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/branches?sort_by=created_at&sort_order=asc' \
|
||||
-H 'accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"branches": [
|
||||
{
|
||||
"id": "br-long-feather-adpbgzlx",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"name": "production",
|
||||
"current_state": "ready",
|
||||
"state_changed_at": "2025-09-10T12:15:01Z",
|
||||
"logical_size": 30785536,
|
||||
"creation_source": "console",
|
||||
"primary": true,
|
||||
"default": true,
|
||||
"protected": false,
|
||||
"cpu_used_sec": 82,
|
||||
"compute_time_seconds": 82,
|
||||
"active_time_seconds": 316,
|
||||
"written_data_bytes": 29060360,
|
||||
"data_transfer_bytes": 0,
|
||||
"created_at": "2025-09-10T12:14:58Z",
|
||||
"updated_at": "2025-09-10T12:35:33Z",
|
||||
"created_by": {
|
||||
"name": "<USER_NAME>",
|
||||
"image": "<USER_IMAGE_URL>"
|
||||
},
|
||||
"init_source": "parent-data"
|
||||
},
|
||||
{
|
||||
"id": "br-super-wildflower-adniii9u",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"parent_id": "br-long-feather-adpbgzlx",
|
||||
"parent_lsn": "0/1A33BC8",
|
||||
"parent_timestamp": "2025-09-10T12:15:03Z",
|
||||
"name": "development",
|
||||
"current_state": "ready",
|
||||
"state_changed_at": "2025-09-10T12:15:04Z",
|
||||
"logical_size": 30842880,
|
||||
"creation_source": "console",
|
||||
"primary": false,
|
||||
"default": false,
|
||||
"protected": false,
|
||||
"cpu_used_sec": 78,
|
||||
"compute_time_seconds": 78,
|
||||
"active_time_seconds": 312,
|
||||
"written_data_bytes": 310120,
|
||||
"data_transfer_bytes": 0,
|
||||
"created_at": "2025-09-10T12:15:04Z",
|
||||
"updated_at": "2025-09-10T12:35:33Z",
|
||||
"created_by": {
|
||||
"name": "<USER_NAME>",
|
||||
"image": "<USER_IMAGE_URL>"
|
||||
},
|
||||
"init_source": "parent-data"
|
||||
}
|
||||
],
|
||||
"annotations": {
|
||||
"br-long-feather-adpbgzlx": {
|
||||
"object": {
|
||||
"type": "console/branch",
|
||||
"id": "br-long-feather-adpbgzlx"
|
||||
},
|
||||
"value": {
|
||||
"environment": "production"
|
||||
},
|
||||
"created_at": "2025-09-10T12:14:58Z",
|
||||
"updated_at": "2025-09-10T12:14:58Z"
|
||||
}
|
||||
},
|
||||
"pagination": {
|
||||
"sort_by": "created_at",
|
||||
"sort_order": "ASC"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Retrieve branch details
|
||||
|
||||
1. Action: Retrieves detailed information about a specific branch, including its parent, creation timestamp, and state.
|
||||
2. Endpoint: `GET /projects/{project_id}/branches/{branch_id}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/branches/br-super-wildflower-adniii9u' \
|
||||
-H 'accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
Example Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"branch": {
|
||||
"id": "br-super-wildflower-adniii9u",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"parent_id": "br-long-feather-adpbgzlx",
|
||||
"parent_lsn": "0/1A33BC8",
|
||||
"parent_timestamp": "2025-09-10T12:15:03Z",
|
||||
"name": "development",
|
||||
"current_state": "ready",
|
||||
"state_changed_at": "2025-09-10T12:15:04Z",
|
||||
"logical_size": 30842880,
|
||||
"creation_source": "console",
|
||||
"primary": false,
|
||||
"default": false,
|
||||
"protected": false,
|
||||
"cpu_used_sec": 78,
|
||||
"compute_time_seconds": 78,
|
||||
"active_time_seconds": 312,
|
||||
"written_data_bytes": 310120,
|
||||
"data_transfer_bytes": 0,
|
||||
"created_at": "2025-09-10T12:15:04Z",
|
||||
"updated_at": "2025-09-10T12:35:33Z",
|
||||
"created_by": {
|
||||
"name": "<USER_NAME>",
|
||||
"image": "<USER_IMAGE_URL>"
|
||||
},
|
||||
"init_source": "parent-data"
|
||||
},
|
||||
"annotation": {
|
||||
"object": {
|
||||
"type": "console/branch",
|
||||
"id": "br-super-wildflower-adniii9u"
|
||||
},
|
||||
"value": {
|
||||
"environment": "development"
|
||||
},
|
||||
"created_at": "2025-09-10T12:15:04Z",
|
||||
"updated_at": "2025-09-10T12:15:04Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Update branch
|
||||
|
||||
1. Action: Updates the properties of a specified branch, such as its name, protection status, or expiration time.
|
||||
2. Endpoint: `PATCH /projects/{project_id}/branches/{branch_id}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch to update.
|
||||
4. Body Parameters:
|
||||
`branch` (object, required): The container for the branch attributes to update.
|
||||
- `name` (string, optional): A new name for the branch (max 256 characters).
|
||||
- `protected` (boolean, optional): Set to `true` to protect the branch or `false` to unprotect it.
|
||||
- `expires_at` (string or null, optional): Set a new RFC 3339 expiration timestamp or `null` to remove the expiration.
|
||||
|
||||
Example: Change branch name:
|
||||
|
||||
```bash
|
||||
curl -X 'PATCH' \
|
||||
'https://console.neon.tech/api/v2/projects/hidden-river-50598307/branches/br-damp-glitter-adqd4hk5' \
|
||||
-H 'accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"branch": {
|
||||
"name": "updated-branch-name"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"branch": {
|
||||
"id": "br-damp-glitter-adqd4hk5",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"parent_id": "br-super-wildflower-adniii9u",
|
||||
"parent_lsn": "0/1A7F730",
|
||||
"parent_timestamp": "2025-09-10T12:15:05Z",
|
||||
"name": "updated-branch-name",
|
||||
"current_state": "ready",
|
||||
"state_changed_at": "2025-09-10T16:45:52Z",
|
||||
"logical_size": 30842880,
|
||||
"creation_source": "console",
|
||||
"primary": false,
|
||||
"default": false,
|
||||
"protected": false,
|
||||
"cpu_used_sec": 68,
|
||||
"compute_time_seconds": 68,
|
||||
"active_time_seconds": 268,
|
||||
"written_data_bytes": 0,
|
||||
"data_transfer_bytes": 0,
|
||||
"created_at": "2025-09-10T16:45:52Z",
|
||||
"updated_at": "2025-09-10T16:55:30Z",
|
||||
"created_by": {
|
||||
"name": "<USER_NAME>",
|
||||
"image": "<USER_IMAGE_URL>"
|
||||
},
|
||||
"init_source": "parent-data"
|
||||
},
|
||||
"operations": []
|
||||
}
|
||||
```
|
||||
|
||||
### Delete branch
|
||||
|
||||
1. Action: Deletes the specified branch from a project. This action will also place all associated compute endpoints into an idle state, breaking any active client connections.
|
||||
2. Endpoint: `DELETE /projects/{project_id}/branches/{branch_id}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch to delete.
|
||||
4. Constraints:
|
||||
- You cannot delete a project's root or default branch.
|
||||
- You cannot delete a branch that has child branches. You must delete all child branches first.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl -X 'DELETE' \
|
||||
'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}' \
|
||||
-H 'accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### List branch endpoints
|
||||
|
||||
1. Action: Retrieves a list of all compute endpoints that are associated with a specific branch.
|
||||
2. Endpoint: `GET /projects/{project_id}/branches/{branch_id}/endpoints`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch whose endpoints you want to list.
|
||||
4. A branch can have one `read_write` compute endpoint and multiple `read_only` endpoints. This method returns an array of all endpoints currently attached to the specified branch.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/branches/br-super-wildflower-adniii9u/endpoints' \
|
||||
-H 'accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
## Manage databases
|
||||
|
||||
### Create database
|
||||
|
||||
1. Action: Creates a new database within a specified branch. A branch can contain multiple databases.
|
||||
2. Endpoint: `POST /projects/{project_id}/branches/{branch_id}/databases`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch where the database will be created.
|
||||
4. Body Parameters:
|
||||
`database` (object, required): The container for the new database's properties.
|
||||
- `name` (string, required): The name for the new database.
|
||||
- `owner_name` (string, required): The name of an existing role that will own the database.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/branches/br-super-wildflower-adniii9u/databases' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"database": {
|
||||
"name": "my_new_app_db",
|
||||
"owner_name": "app_owner_role"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### List databases
|
||||
|
||||
1. Action: Retrieves a list of all databases within a specified branch.
|
||||
2. Endpoint: `GET /projects/{project_id}/branches/{branch_id}/databases`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/branches/br-super-wildflower-adniii9u/databases' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Retrieve database details
|
||||
|
||||
1. Action: Retrieves detailed information about a specific database within a branch.
|
||||
2. Endpoint: `GET /projects/{project_id}/branches/{branch_id}/databases/{database_name}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch.
|
||||
- `database_name` (string, required): The name of the database.
|
||||
|
||||
### Update database
|
||||
|
||||
1. Action: Updates the properties of a specified database, such as its name or owner.
|
||||
2. Endpoint: `PATCH /projects/{project_id}/branches/{branch_id}/databases/{database_name}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch.
|
||||
- `database_name` (string, required): The current name of the database to update.
|
||||
4. Body Parameters:
|
||||
`database` (object, required): The container for the database attributes to update.
|
||||
- `name` (string, optional): A new name for the database.
|
||||
- `owner_name` (string, optional): The name of a different existing role to become the new owner.
|
||||
|
||||
### Delete database
|
||||
|
||||
1. Action: Deletes the specified database from a branch. This action is permanent and cannot be undone.
|
||||
2. Endpoint: `DELETE /projects/{project_id}/branches/{branch_id}/databases/{database_name}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch.
|
||||
- `database_name` (string, required): The name of the database to delete.
|
||||
|
||||
## Manage roles
|
||||
|
||||
### Create role
|
||||
|
||||
1. Action: Creates a new Postgres role in a specified branch. This action may drop existing connections to the active compute endpoint.
|
||||
2. Endpoint: `POST /projects/{project_id}/branches/{branch_id}/roles`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch where the role will be created.
|
||||
4. Body Parameters:
|
||||
`role` (object, required): The container for the new role's properties.
|
||||
- `name` (string, required): The name for the new role. Cannot exceed 63 bytes in length.
|
||||
- `no_login` (boolean, optional): If `true`, creates a role that cannot be used to log in. Defaults to `false`.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/branches/br-super-wildflower-adniii9u/roles' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"role": {
|
||||
"name": "new_app_user"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### List roles
|
||||
|
||||
1. Action: Retrieves a list of all Postgres roles from the specified branch.
|
||||
2. Endpoint: `GET /projects/{project_id}/branches/{branch_id}/roles`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch.
|
||||
|
||||
### Retrieve role details
|
||||
|
||||
1. Action: Retrieves detailed information about a specific Postgres role within a branch.
|
||||
2. Endpoint: `GET /projects/{project_id}/branches/{branch_id}/roles/{role_name}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch.
|
||||
- `role_name` (string, required): The name of the role.
|
||||
|
||||
### Delete role
|
||||
|
||||
1. Action: Deletes the specified Postgres role from the branch. This action is permanent.
|
||||
2. Endpoint: `DELETE /projects/{project_id}/branches/{branch_id}/roles/{role_name}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `branch_id` (string, required): The unique identifier of the branch.
|
||||
- `role_name` (string, required): The name of the role to delete.
|
||||
211
neon-postgres/references/neon-rest-api/endpoints.md
Normal file
211
neon-postgres/references/neon-rest-api/endpoints.md
Normal file
@@ -0,0 +1,211 @@
|
||||
## Overview
|
||||
|
||||
This section provides rules for managing compute endpoints associated with branches in a project. Compute endpoints are Neon compute instances that allow you to connect to and interact with your databases.
|
||||
|
||||
## Manage compute endpoints
|
||||
|
||||
### Create compute endpoint
|
||||
|
||||
1. Action: Creates a new compute endpoint (a Neon compute instance) and associates it with a specified branch.
|
||||
2. Endpoint: `POST /projects/{project_id}/endpoints`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
4. Body Parameters:
|
||||
`endpoint` (object, required): The container for the new endpoint's properties.
|
||||
- `branch_id` (string, required): The ID of the branch to associate the endpoint with.
|
||||
- `type` (string, required): The endpoint type. A branch can have only one `read_write` endpoint but multiple `read_only` endpoints. Allowed values: `read_write`, `read_only`.
|
||||
- `region_id` (string, optional): The region where the endpoint will be created. Must match the project's region.
|
||||
- `autoscaling_limit_min_cu` (number, optional): The minimum number of Compute Units (CU). Minimum `0.25`.
|
||||
- `autoscaling_limit_max_cu` (number, optional): The maximum number of Compute Units (CU). Minimum `0.25`.
|
||||
- `provisioner` (string, optional): The compute provisioner. Specify `k8s-neonvm` to enable Autoscaling. Allowed values: `k8s-pod`, `k8s-neonvm`.
|
||||
- `suspend_timeout_seconds` (integer, optional): Duration of inactivity in seconds before suspending the compute. Ranges from -1 (never suspend) to 604800 (1 week).
|
||||
- `disabled` (boolean, optional): If `true`, restricts connections to the endpoint.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/endpoints' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"endpoint": {
|
||||
"branch_id": "br-your-branch-id",
|
||||
"type": "read_only"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Example Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"endpoint": {
|
||||
"host": "ep-proud-mud-adwmnxz4.c-2.us-east-1.aws.neon.tech",
|
||||
"id": "ep-proud-mud-adwmnxz4",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-super-wildflower-adniii9u",
|
||||
"autoscaling_limit_min_cu": 0.25,
|
||||
"autoscaling_limit_max_cu": 2,
|
||||
"region_id": "aws-us-east-1",
|
||||
"type": "read_only",
|
||||
"current_state": "init",
|
||||
"pending_state": "active",
|
||||
"settings": {},
|
||||
"pooler_enabled": false,
|
||||
"pooler_mode": "transaction",
|
||||
"disabled": false,
|
||||
"passwordless_access": true,
|
||||
"creation_source": "console",
|
||||
"created_at": "2025-09-11T06:25:12Z",
|
||||
"updated_at": "2025-09-11T06:25:12Z",
|
||||
"proxy_host": "c-2.us-east-1.aws.neon.tech",
|
||||
"suspend_timeout_seconds": 0,
|
||||
"provisioner": "k8s-neonvm"
|
||||
},
|
||||
"operations": [
|
||||
{
|
||||
"id": "4d10642f-5212-4517-ad60-afd28c9096e2",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-super-wildflower-adniii9u",
|
||||
"endpoint_id": "ep-proud-mud-adwmnxz4",
|
||||
"action": "start_compute",
|
||||
"status": "running",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-11T06:25:12Z",
|
||||
"updated_at": "2025-09-11T06:25:12Z",
|
||||
"total_duration_ms": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### List compute endpoints
|
||||
|
||||
1. Action: Retrieves a list of all compute endpoints for the specified project.
|
||||
2. Endpoint: `GET /projects/{project_id}/endpoints`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/endpoints' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Retrieve compute endpoint details
|
||||
|
||||
1. Action: Retrieves detailed information about a specific compute endpoint, including its configuration (e.g., autoscaling limits), current state (`active` or `idle`), and associated branch ID.
|
||||
2. Endpoint: `GET /projects/{project_id}/endpoints/{endpoint_id}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `endpoint_id` (string, required): The unique identifier of the compute endpoint).
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/endpoints/ep-proud-mud-adwmnxz4' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Update compute endpoint
|
||||
|
||||
1. Action: Updates the configuration of a specified compute endpoint.
|
||||
2. Endpoint: `PATCH /projects/{project_id}/endpoints/{endpoint_id}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `endpoint_id` (string, required): The unique identifier of the compute endpoint.
|
||||
4. Body Parameters:
|
||||
`endpoint` (object, required): The container for the endpoint attributes to update.
|
||||
- `autoscaling_limit_min_cu` (number, optional): A new minimum number of Compute Units (CU).
|
||||
- `autoscaling_limit_max_cu` (number, optional): A new maximum number of Compute Units (CU).
|
||||
- `suspend_timeout_seconds` (integer, optional): A new inactivity period in seconds before suspension.
|
||||
- `disabled` (boolean, optional): Set to `true` to disable connections or `false` to enable them.
|
||||
- `provisioner` (string, optional): Change the compute provisioner.
|
||||
|
||||
Example: Update autoscaling limits
|
||||
|
||||
```bash
|
||||
curl -X 'PATCH' \
|
||||
'https://console.neon.tech/api/v2/projects/hidden-river-50598307/endpoints/ep-proud-mud-adwmnxz4' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"endpoint": {
|
||||
"autoscaling_limit_min_cu": 0.5,
|
||||
"autoscaling_limit_max_cu": 1
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Delete compute endpoint
|
||||
|
||||
1. Action: Deletes the specified compute endpoint. This action drops any existing network connections to the endpoint.
|
||||
2. Endpoint: `DELETE /projects/{project_id}/endpoints/{endpoint_id}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `endpoint_id` (string, required): The unique identifier of the compute endpoint to delete.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl -X 'DELETE' \
|
||||
'https://console.neon.tech/api/v2/projects/hidden-river-50598307/endpoints/ep-proud-mud-adwmnxz4' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Start compute endpoint
|
||||
|
||||
1. Action: Manually starts a compute endpoint that is currently in an `idle` state. The endpoint is ready for connections once the start operation completes successfully.
|
||||
2. Endpoint: `POST /projects/{project_id}/endpoints/{endpoint_id}/start`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `endpoint_id` (string, required): The unique identifier of the compute endpoint.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl -X 'POST' \
|
||||
'https://console.neon.tech/api/v2/projects/hidden-river-50598307/endpoints/ep-ancient-brook-ad5ea04d/start' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Suspend compute endpoint
|
||||
|
||||
1. Action: Manually suspends an `active` compute endpoint, forcing it into an `idle` state. This will immediately drop any active connections to the endpoint.
|
||||
2. Endpoint: `POST /projects/{project_id}/endpoints/{endpoint_id}/suspend`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `endpoint_id` (string, required): The unique identifier of the compute endpoint.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl -X 'POST' \
|
||||
'https://console.neon.tech/api/v2/projects/hidden-river-50598307/endpoints/ep-ancient-brook-ad5ea04d/suspend' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Restart compute endpoint
|
||||
|
||||
1. Action: Restarts the specified compute endpoint. This involves an immediate suspend operation followed by a start operation. This is useful for applying configuration changes or refreshing the compute instance. All active connections will be dropped.
|
||||
2. Endpoint: `POST /projects/{project_id}/endpoints/{endpoint_id}/restart`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project.
|
||||
- `endpoint_id` (string, required): The unique identifier of the compute endpoint.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl -X 'POST' \
|
||||
'https://console.neon.tech/api/v2/projects/hidden-river-50598307/endpoints/ep-ancient-brook-ad5ea04d/restart' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
67
neon-postgres/references/neon-rest-api/guidelines.md
Normal file
67
neon-postgres/references/neon-rest-api/guidelines.md
Normal file
@@ -0,0 +1,67 @@
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive set of rules and guidelines for an AI agent to interact with the Neon API. The Neon API is a RESTful service that allows for programmatic management of all Neon resources. Adherence to these rules ensures correct, efficient, and safe API usage.
|
||||
|
||||
### General API guidelines
|
||||
|
||||
All Neon API requests must be made to the following base URL:
|
||||
|
||||
```
|
||||
https://console.neon.tech/api/v2/
|
||||
```
|
||||
|
||||
To construct a full request URL, append the specific endpoint path to this base URL.
|
||||
|
||||
### Authentication
|
||||
|
||||
- All API requests must be authenticated using a Neon API key.
|
||||
- The API key must be included in the `Authorization` header using the `Bearer` authentication scheme.
|
||||
- The header should be formatted as: `Authorization: Bearer $NEON_API_KEY`, where `$NEON_API_KEY` is a valid Neon API key.
|
||||
- A request without a valid `Authorization` header will fail with a `401 Unauthorized` status code.
|
||||
|
||||
### API rate limiting
|
||||
|
||||
- Neon limits API requests to 700 requests per minute (approximately 11 per second).
|
||||
- Bursts of up to 40 requests per second per route are permitted.
|
||||
- If the rate limit is exceeded, the API will respond with an `HTTP 429 Too Many Requests` error.
|
||||
- Your application logic must handle `429` errors and implement a retry strategy with appropriate backoff.
|
||||
|
||||
### Neon Core Concepts
|
||||
|
||||
To effectively use the Neon Python SDK, it's essential to understand the hierarchy and purpose of its core resources. The following table provides a high-level overview of each concept.
|
||||
|
||||
| Concept | Description | Analogy/Purpose | Key Relationship |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| Organization | The highest-level container, managing billing, users, and multiple projects. | A GitHub Organization or a company's cloud account. | Contains one or more Projects. |
|
||||
| Project | The primary container that contains all related database resources for a single application or service. | A Git repository or a top-level folder for an application. | Lives within an Organization (or a personal account). Contains Branches. |
|
||||
| Branch | A lightweight, copy-on-write clone of a database's state at a specific point in time. | A `git branch`. Used for isolated development, testing, staging, or previews without duplicating storage costs. | Belongs to a Project. Contains its own set of Databases and Roles, cloned from its parent. |
|
||||
| Compute Endpoint | The actual running PostgreSQL instance that you connect to. It provides the CPU and RAM for processing queries. | The "server" or "engine" for your database. It can be started, suspended (scaled to zero), and resized. | Is attached to a single Branch. Your connection string points to a Compute Endpoint's hostname. |
|
||||
| Database | A logical container for your data (tables, schemas, views) within a branch. It follows standard PostgreSQL conventions. | A single database within a PostgreSQL server instance. | Exists within a Branch. A branch can have multiple databases. |
|
||||
| Role | A PostgreSQL role used for authentication (logging in) and authorization (permissions to access data). | A database user account with a username and password. | Belongs to a Branch. Roles from a parent branch are copied to child branches upon creation. |
|
||||
| API Key | A secret token used to authenticate requests to the Neon API. Keys have different scopes (Personal, Organization, Project-scoped). | A password for programmatic access, allowing you to manage all other Neon resources. | Authenticates actions on Organizations, Projects, Branches, etc. |
|
||||
| Operation | An asynchronous action performed by the Neon control plane, such as creating a branch or starting a compute. | A background job or task. Its status can be polled to know when an action is complete. | Associated with a Project and often a specific Branch or Endpoint. Essential for scripting API calls. |
|
||||
|
||||
### Understanding API key types
|
||||
|
||||
When performing actions via the API, you must select the correct type of API key based on the required scope and permissions. There are three types:
|
||||
|
||||
1. Personal API Key
|
||||
|
||||
- Scope: Accesses all projects that the user who created the key is a member of.
|
||||
- Permissions: The key has the same permissions as its owner. If the user's access is revoked from an organization, the key loses access too.
|
||||
- Best For: Individual use, scripting, and tasks tied to a specific user's permissions.
|
||||
- Created By: Any user.
|
||||
|
||||
2. Organization API Key
|
||||
|
||||
- Scope: Accesses all projects and resources within an entire organization.
|
||||
- Permissions: Has admin-level access across the organization, independent of any single user. It remains valid even if the creator leaves the organization.
|
||||
- Best For: CI/CD pipelines, organization-wide automation, and service accounts that need broad access.
|
||||
- Created By: Organization administrators only.
|
||||
|
||||
3. Project-scoped API Key
|
||||
|
||||
- Scope: Access is strictly limited to a single, specified project.
|
||||
- Permissions: Cannot perform organization-level actions (like creating new projects) or delete the project it is scoped to. This is the most secure and limited key type.
|
||||
- Best For: Project-specific integrations, third-party services, or automation that should be isolated to one project.
|
||||
- Created By: Any organization member.
|
||||
92
neon-postgres/references/neon-rest-api/keys.md
Normal file
92
neon-postgres/references/neon-rest-api/keys.md
Normal file
@@ -0,0 +1,92 @@
|
||||
## Overview
|
||||
|
||||
This document outlines the rules for managing Neon API keys programmatically. It covers listing existing keys, creating new keys, and revoking keys.
|
||||
|
||||
### Important note on creating API keys
|
||||
|
||||
To create new API keys using the API, you must already possess a valid Personal API Key. The first key must be created from the Neon Console. You can ask the user to create one for you if you do not have one.
|
||||
|
||||
### List API keys
|
||||
|
||||
- Endpoint: `GET /api_keys`
|
||||
- Authorization: Use a Personal API Key.
|
||||
|
||||
Example request:
|
||||
|
||||
```bash
|
||||
curl "https://console.neon.tech/api/v2/api_keys" \
|
||||
-H "Authorization: Bearer $PERSONAL_API_KEY"
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 2291506,
|
||||
"name": "my-personal-key",
|
||||
"created_at": "2025-09-10T09:44:04Z",
|
||||
"created_by": {
|
||||
"id": "487de658-08ba-4363-b387-86d18b9ad1c8",
|
||||
"name": "<USER_NAME>",
|
||||
"image": "<USER_IMAGE_URL>"
|
||||
},
|
||||
"last_used_at": "2025-09-10T09:44:09Z",
|
||||
"last_used_from_addr": "49.43.218.132,34.211.200.85"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Create an API key
|
||||
|
||||
- Endpoint: `POST /api_keys`
|
||||
- Authorization: Use a Personal API Key.
|
||||
- Body: Must include a `key_name`.
|
||||
|
||||
Example request:
|
||||
|
||||
```bash
|
||||
curl https://console.neon.tech/api/v2/api_keys \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $PERSONAL_API_KEY" \
|
||||
-d '{"key_name": "my-new-key"}'
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 2291515,
|
||||
"key": "napi_9tlr13774gizljemrr133j5koy3bmsphj8iu38mh0yjl9q4r1b0jy2wuhhuxouzr",
|
||||
"name": "my-new-key",
|
||||
"created_at": "2025-09-10T09:47:59Z",
|
||||
"created_by": "487de658-08ba-4363-b387-86d18b9ad1c8"
|
||||
}
|
||||
```
|
||||
|
||||
### Revoke an API key
|
||||
|
||||
- Endpoint: `DELETE /api_keys/{key_id}`
|
||||
- Authorization: Use a Personal API Key.
|
||||
|
||||
Example request:
|
||||
|
||||
```bash
|
||||
curl -X DELETE \
|
||||
'https://console.neon.tech/api/v2/api_keys/2291515' \
|
||||
-H "Authorization: Bearer $PERSONAL_API_KEY"
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 2291515,
|
||||
"name": "mynewkey",
|
||||
"created_at": "2025-09-10T09:47:59Z",
|
||||
"created_by": "487de658-08ba-4363-b387-86d18b9ad1c8",
|
||||
"last_used_at": "2025-09-10T09:53:01Z",
|
||||
"last_used_from_addr": "2405:201:c01f:7013:d962:2b4f:2740:9750",
|
||||
"revoked": true
|
||||
}
|
||||
```
|
||||
146
neon-postgres/references/neon-rest-api/operations.md
Normal file
146
neon-postgres/references/neon-rest-api/operations.md
Normal file
@@ -0,0 +1,146 @@
|
||||
## Overview
|
||||
|
||||
This document outlines the rules for managing and monitoring long-running operations in Neon, including branch creation and compute management.
|
||||
|
||||
## Operations
|
||||
|
||||
An operation is an action performed by the Neon Control Plane (e.g., `create_branch`, `start_compute`). When using the API programmatically, it is crucial to monitor the status of long-running operations to ensure one has completed before starting another that depends on it. Operations older than 6 months may be deleted from Neon's systems.
|
||||
|
||||
### List operations
|
||||
|
||||
1. Action: Retrieves a list of operations for the specified Neon project. The number of operations can be large, so pagination is recommended.
|
||||
2. Endpoint: `GET /projects/{project_id}/operations`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project whose operations you want to list.
|
||||
4. Query Parameters:
|
||||
- `limit` (integer, optional): The number of operations to return in the response. Must be between 1 and 1000.
|
||||
- `cursor` (string, optional): The cursor value from a previous response to fetch the next page of operations.
|
||||
5. Procedure:
|
||||
- Make an initial request with a `limit` to get the first page of results.
|
||||
- The response will contain a `pagination.cursor` value.
|
||||
- To get the next page, make a subsequent request including both the `limit` and the `cursor` from the previous response.
|
||||
|
||||
Example request
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/operations' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"operations": [
|
||||
{
|
||||
"id": "639f7f73-0b76-4749-a767-2d3c627ca5a6",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-long-feather-adpbgzlx",
|
||||
"endpoint_id": "ep-round-morning-adtpn2oc",
|
||||
"action": "apply_config",
|
||||
"status": "finished",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T12:15:23Z",
|
||||
"updated_at": "2025-09-10T12:15:23Z",
|
||||
"total_duration_ms": 87
|
||||
},
|
||||
{
|
||||
"id": "b5a7882b-a5b3-4292-ad27-bffe733feae4",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-super-wildflower-adniii9u",
|
||||
"endpoint_id": "ep-ancient-brook-ad5ea04d",
|
||||
"action": "apply_config",
|
||||
"status": "finished",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T12:15:23Z",
|
||||
"updated_at": "2025-09-10T12:15:23Z",
|
||||
"total_duration_ms": 49
|
||||
},
|
||||
{
|
||||
"id": "36a1cba0-97f1-476d-af53-d9e0d3a3606d",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-super-wildflower-adniii9u",
|
||||
"endpoint_id": "ep-ancient-brook-ad5ea04d",
|
||||
"action": "start_compute",
|
||||
"status": "finished",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T12:15:04Z",
|
||||
"updated_at": "2025-09-10T12:15:05Z",
|
||||
"total_duration_ms": 913
|
||||
},
|
||||
{
|
||||
"id": "409c35ef-cbc3-4f1b-a4ca-f2de319f5360",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-super-wildflower-adniii9u",
|
||||
"action": "create_branch",
|
||||
"status": "finished",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T12:15:04Z",
|
||||
"updated_at": "2025-09-10T12:15:04Z",
|
||||
"total_duration_ms": 136
|
||||
},
|
||||
{
|
||||
"id": "274e240f-e2fb-4719-b796-c1ab7c4ae91c",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-long-feather-adpbgzlx",
|
||||
"endpoint_id": "ep-round-morning-adtpn2oc",
|
||||
"action": "start_compute",
|
||||
"status": "finished",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T12:14:58Z",
|
||||
"updated_at": "2025-09-10T12:15:03Z",
|
||||
"total_duration_ms": 4843
|
||||
},
|
||||
{
|
||||
"id": "22ef6fbd-21c5-4cdb-9825-b0f9afddbb0d",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-long-feather-adpbgzlx",
|
||||
"action": "create_timeline",
|
||||
"status": "finished",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T12:14:58Z",
|
||||
"updated_at": "2025-09-10T12:15:01Z",
|
||||
"total_duration_ms": 3096
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"cursor": "2025-09-10T12:14:58.848485Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Retrieve operation details
|
||||
|
||||
1. Action: Retrieves the details and status of a single, specified operation. The `operation_id` is found in the response body of the initial API call that initiated it, or by listing operations.
|
||||
2. Endpoint: `GET /projects/{project_id}/operations/{operation_id}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project where the operation occurred.
|
||||
- `operation_id` (UUID, required): The unique identifier of the operation. This ID is returned in the response body of the API call that initiated the operation.
|
||||
|
||||
Example request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/operations/274e240f-e2fb-4719-b796-c1ab7c4ae91c' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": {
|
||||
"id": "274e240f-e2fb-4719-b796-c1ab7c4ae91c",
|
||||
"project_id": "hidden-river-50598307",
|
||||
"branch_id": "br-long-feather-adpbgzlx",
|
||||
"endpoint_id": "ep-round-morning-adtpn2oc",
|
||||
"action": "start_compute",
|
||||
"status": "finished",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T12:14:58Z",
|
||||
"updated_at": "2025-09-10T12:15:03Z",
|
||||
"total_duration_ms": 4843
|
||||
}
|
||||
}
|
||||
```
|
||||
199
neon-postgres/references/neon-rest-api/organizations.md
Normal file
199
neon-postgres/references/neon-rest-api/organizations.md
Normal file
@@ -0,0 +1,199 @@
|
||||
## Overview
|
||||
|
||||
This section provides rules for managing organizations, their members, invitations, and organization API keys. Organizations allow multiple users to collaborate on projects and share resources within Neon.
|
||||
|
||||
## Manage organizations
|
||||
|
||||
### Retrieve organization details
|
||||
|
||||
1. Action: Retrieves detailed information about a specific organization.
|
||||
2. Endpoint: `GET /organizations/{org_id}`
|
||||
3. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/organizations/{org_id}' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### List organization members
|
||||
|
||||
1. Action: Retrieves a list of all members belonging to the specified organization.
|
||||
2. Endpoint: `GET /organizations/{org_id}/members`
|
||||
3. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/organizations/{org_id}/members' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Retrieve organization member details
|
||||
|
||||
1. Action: Retrieves information about a specific member of an organization.
|
||||
2. Endpoint: `GET /organizations/{org_id}/members/{member_id}`
|
||||
3. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
- `member_id` (UUID, required): The unique identifier of the organization member.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/organizations/{org_id}/members/{member_id}' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Update role for organization member
|
||||
|
||||
1. Action: Updates the role of a specified member within an organization.
|
||||
2. Prerequisite: This action can only be performed by an organization `admin`.
|
||||
3. Endpoint: `PATCH /organizations/{org_id}/members/{member_id}`
|
||||
4. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
- `member_id` (UUID, required): The unique identifier of the organization member.
|
||||
5. Body Parameters:
|
||||
- `role` (string, required): The new role for the member. Allowed values: `admin`, `member`.
|
||||
|
||||
Example: Change a member's role to admin
|
||||
|
||||
```bash
|
||||
curl -X 'PATCH' \
|
||||
'https://console.neon.tech/api/v2/organizations/{org_id}/members/{member_id}' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"role": "admin"}'
|
||||
```
|
||||
|
||||
### Remove member from organization
|
||||
|
||||
1. Action: Removes a specified member from an organization.
|
||||
2. Prerequisites:
|
||||
- This action can only be performed by an organization `admin`.
|
||||
- An admin cannot be removed if they are the only admin left in the organization.
|
||||
3. Endpoint: `DELETE /organizations/{org_id}/members/{member_id}`
|
||||
4. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
- `member_id` (UUID, required): The unique identifier of the organization member to remove.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl -X 'DELETE' \
|
||||
'https://console.neon.tech/api/v2/organizations/{org_id}/members/{member_id}' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Create organization invitations
|
||||
|
||||
1. Action: Creates and sends one or more email invitations for users to join a specific organization.
|
||||
2. Endpoint: `POST /organizations/{org_id}/invitations`
|
||||
3. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
4. Body Parameters:
|
||||
`invitations` (array of objects, required): A list of invitations to create.
|
||||
- `email` (string, required): The email address of the user to invite.
|
||||
- `role` (string, required): The role the invited user will have. Allowed values: `admin`, `member`.
|
||||
|
||||
Example: Invite two users with different roles
|
||||
|
||||
```bash
|
||||
curl -X 'POST' \
|
||||
'https://console.neon.tech/api/v2/organizations/{org_id}/invitations' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"invitations": [
|
||||
{
|
||||
"email": "developer@example.com",
|
||||
"role": "member"
|
||||
},
|
||||
{
|
||||
"email": "manager@example.com",
|
||||
"role": "admin"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### List organization invitations
|
||||
|
||||
1. Action: Retrieves information about outstanding invitations for the specified organization.
|
||||
2. Endpoint: `GET /organizations/{org_id}/invitations`
|
||||
3. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/organizations/{org_id}/invitations' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Create organization API key
|
||||
|
||||
1. Action: Creates a new API key for the specified organization. The key can be scoped to the entire organization or limited to a single project within it.
|
||||
2. Endpoint: `POST /organizations/{org_id}/api_keys`
|
||||
3. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
4. Body Parameters:
|
||||
- `key_name` (string, required): A user-specified name for the API key (max 64 characters).
|
||||
- `project_id` (string, optional): If provided, the API key's access will be restricted to only this project.
|
||||
5. Authorization: Use a Personal API Key of an organization `admin` to create organization API keys.
|
||||
|
||||
Example: Create a project-scoped API key
|
||||
|
||||
```bash
|
||||
curl -X 'POST' \
|
||||
'https://console.neon.tech/api/v2/organizations/{org_id}/api_keys' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $PERSONAL_API_KEY_OF_ADMIN" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"key_name": "ci-pipeline-key-for-project-x",
|
||||
"project_id": "project-id-123"
|
||||
}'
|
||||
```
|
||||
|
||||
### List organization API keys
|
||||
|
||||
1. Action: Retrieves a list of all API keys created for the specified organization.
|
||||
2. Endpoint: `GET /organizations/{org_id}/api_keys`
|
||||
3. Note: The response includes metadata about the keys (like `id` and `name`) but does not include the secret key tokens themselves. Tokens are only visible upon creation.
|
||||
4. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/organizations/{org_id}/api_keys' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
### Revoke organization API key
|
||||
|
||||
1. Action: Permanently revokes the specified organization API key.
|
||||
2. Endpoint: `DELETE /organizations/{org_id}/api_keys/{key_id}`
|
||||
3. Path Parameters:
|
||||
- `org_id` (string, required): The unique identifier of the organization.
|
||||
- `key_id` (integer, required): The unique identifier of the API key to revoke. You can obtain this ID by listing the organization's API keys.
|
||||
|
||||
Example Request:
|
||||
|
||||
```bash
|
||||
curl -X 'DELETE' \
|
||||
'https://console.neon.tech/api/v2/organizations/{org_id}/api_keys/{key_id}' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
576
neon-postgres/references/neon-rest-api/projects.md
Normal file
576
neon-postgres/references/neon-rest-api/projects.md
Normal file
@@ -0,0 +1,576 @@
|
||||
## Overview
|
||||
|
||||
This document outlines the rules for managing Neon projects programmatically. It covers creation, retrieval, updates, and deletion.
|
||||
|
||||
## Manage projects
|
||||
|
||||
### List projects
|
||||
|
||||
1. Action: Retrieves a list of all projects accessible to the account associated with the API key. This is the primary method for obtaining `project_id` values required for other API calls.
|
||||
2. Endpoint: `GET /projects`
|
||||
3. Query Parameters:
|
||||
- `limit` (optional, integer, default: 10): Specifies the number of projects to return, from 1 to 400.
|
||||
- `cursor` (optional, string): Used for pagination. Provide the `cursor` value from a previous response to fetch the next set of projects.
|
||||
- `search` (optional, string): Filters projects by a partial match on the project `name` or `id`.
|
||||
- `org_id` (optional, string): Filters projects by a specific organization ID.
|
||||
4. When iterating through all projects, use a combination of the `limit` and `cursor` parameters to handle pagination correctly.
|
||||
|
||||
Example request:
|
||||
|
||||
```bash
|
||||
# Retrieve the first 10 projects
|
||||
curl 'https://console.neon.tech/api/v2/projects?limit=10' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"projects": [
|
||||
{
|
||||
"id": "old-fire-32990194",
|
||||
"platform_id": "aws",
|
||||
"region_id": "aws-ap-southeast-1",
|
||||
"name": "old-fire-32990194",
|
||||
"provisioner": "k8s-neonvm",
|
||||
"default_endpoint_settings": {
|
||||
"autoscaling_limit_min_cu": 0.25,
|
||||
"autoscaling_limit_max_cu": 2,
|
||||
"suspend_timeout_seconds": 0
|
||||
},
|
||||
"settings": {
|
||||
"allowed_ips": {
|
||||
"ips": [],
|
||||
"protected_branches_only": false
|
||||
},
|
||||
"enable_logical_replication": false,
|
||||
"maintenance_window": {
|
||||
"weekdays": [5],
|
||||
"start_time": "19:00",
|
||||
"end_time": "20:00"
|
||||
},
|
||||
"block_public_connections": false,
|
||||
"block_vpc_connections": false,
|
||||
"hipaa": false
|
||||
},
|
||||
"pg_version": 17,
|
||||
"proxy_host": "ap-southeast-1.aws.neon.tech",
|
||||
"branch_logical_size_limit": 512,
|
||||
"branch_logical_size_limit_bytes": 536870912,
|
||||
"store_passwords": true,
|
||||
"active_time": 0,
|
||||
"cpu_used_sec": 0,
|
||||
"creation_source": "console",
|
||||
"created_at": "2025-09-10T06:58:33Z",
|
||||
"updated_at": "2025-09-10T06:58:39Z",
|
||||
"synthetic_storage_size": 0,
|
||||
"quota_reset_at": "2025-10-01T00:00:00Z",
|
||||
"owner_id": "org-royal-sun-91776391",
|
||||
"compute_last_active_at": "2025-09-10T06:58:38Z",
|
||||
"org_id": "org-royal-sun-91776391",
|
||||
"history_retention_seconds": 86400
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"cursor": "old-fire-32990194"
|
||||
},
|
||||
"applications": {},
|
||||
"integrations": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Create project
|
||||
|
||||
1. Action: Creates a new Neon project. You can specify a wide range of settings at creation time, including the region, Postgres version, default branch and compute configurations, and security settings.
|
||||
2. Endpoint: `POST /projects`
|
||||
3. Body Parameters: The request body must contain a top-level `project` object with the following nested attributes:
|
||||
|
||||
`project` (object, required): The main container for all project settings.
|
||||
- `name` (string, optional): A descriptive name for the project (1-256 characters). If omitted, the project name will be identical to its generated ID.
|
||||
- `pg_version` (integer, optional): The major Postgres version. Defaults to `17`. Supported versions: 14, 15, 16, 17, 18.
|
||||
- `region_id` (string, optional): The identifier for the region where the project will be created (e.g., `aws-us-east-1`).
|
||||
- `org_id` (string, optional): The ID of an organization to which the project will belong. Required if using an Organization API key.
|
||||
- `store_passwords` (boolean, optional): Whether to store role passwords in Neon. Storing passwords is required for features like the SQL Editor and integrations.
|
||||
- `history_retention_seconds` (integer, optional): The duration in seconds (0 to 2,592,000) to retain project history for features like Point-in-Time Restore. Defaults to 86400 (1 day).
|
||||
- `provisioner` (string, optional): The compute provisioner. Specify `k8s-neonvm` to enable Autoscaling. Allowed values: `k8s-pod`, `k8s-neonvm`.
|
||||
- `default_endpoint_settings` (object, optional): Default settings for new compute endpoints created in this project.
|
||||
- `autoscaling_limit_min_cu` (number, optional): The minimum number of Compute Units (CU). Minimum value is `0.25`.
|
||||
- `autoscaling_limit_max_cu` (number, optional): The maximum number of Compute Units (CU). Minimum value is `0.25`.
|
||||
- `suspend_timeout_seconds` (integer, optional): Duration of inactivity in seconds before a compute is suspended. Ranges from -1 (never suspend) to 604800 (1 week). A value of `0` uses the default of 300 seconds (5 minutes).
|
||||
- `settings` (object, optional): Project-wide settings.
|
||||
- `quota` (object, optional): Per-project consumption quotas. A zero or empty value means "unlimited".
|
||||
- `active_time_seconds` (integer, optional): Wall-clock time allowance for active computes.
|
||||
- `compute_time_seconds` (integer, optional): CPU seconds allowance.
|
||||
- `written_data_bytes` (integer, optional): Data written allowance.
|
||||
- `data_transfer_bytes` (integer, optional): Data transferred allowance.
|
||||
- `logical_size_bytes` (integer, optional): Logical data size limit per branch.
|
||||
- `allowed_ips` (object, optional): Configures the IP Allowlist.
|
||||
- `ips` (array of strings, optional): A list of allowed IP addresses or CIDR ranges.
|
||||
- `protected_branches_only` (boolean, optional): If `true`, the IP allowlist applies only to protected branches.
|
||||
- `enable_logical_replication` (boolean, optional): Sets `wal_level=logical`.
|
||||
- `maintenance_window` (object, optional): The time period for scheduled maintenance.
|
||||
- `weekdays` (array of integers, required if `maintenance_window` is set): Days of the week (1=Monday, 7=Sunday).
|
||||
- `start_time` (string, required if `maintenance_window` is set): Start time in "HH:MM" UTC format.
|
||||
- `end_time` (string, required if `maintenance_window` is set): End time in "HH:MM" UTC format.
|
||||
- `branch` (object, optional): Configuration for the project's default branch.
|
||||
- `name` (string, optional): The name for the default branch. Defaults to `main`.
|
||||
- `role_name` (string, optional): The name for the default role. Defaults to `{database_name}_owner`.
|
||||
- `database_name` (string, optional): The name for the default database. Defaults to `neondb`.
|
||||
|
||||
Example request
|
||||
|
||||
```bash
|
||||
curl -X POST 'https://console.neon.tech/api/v2/projects' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"project": {
|
||||
"name": "my-new-api-project",
|
||||
"pg_version": 17
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"project": {
|
||||
"data_storage_bytes_hour": 0,
|
||||
"data_transfer_bytes": 0,
|
||||
"written_data_bytes": 0,
|
||||
"compute_time_seconds": 0,
|
||||
"active_time_seconds": 0,
|
||||
"cpu_used_sec": 0,
|
||||
"id": "sparkling-hill-99143322",
|
||||
"platform_id": "aws",
|
||||
"region_id": "aws-us-west-2",
|
||||
"name": "my-new-api-project",
|
||||
"provisioner": "k8s-neonvm",
|
||||
"default_endpoint_settings": {
|
||||
"autoscaling_limit_min_cu": 0.25,
|
||||
"autoscaling_limit_max_cu": 0.25,
|
||||
"suspend_timeout_seconds": 0
|
||||
},
|
||||
"settings": {
|
||||
"allowed_ips": {
|
||||
"ips": [],
|
||||
"protected_branches_only": false
|
||||
},
|
||||
"enable_logical_replication": false,
|
||||
"maintenance_window": {
|
||||
"weekdays": [5],
|
||||
"start_time": "07:00",
|
||||
"end_time": "08:00"
|
||||
},
|
||||
"block_public_connections": false,
|
||||
"block_vpc_connections": false,
|
||||
"hipaa": false
|
||||
},
|
||||
"pg_version": 17,
|
||||
"proxy_host": "c-2.us-west-2.aws.neon.tech",
|
||||
"branch_logical_size_limit": 512,
|
||||
"branch_logical_size_limit_bytes": 536870912,
|
||||
"store_passwords": true,
|
||||
"creation_source": "console",
|
||||
"history_retention_seconds": 86400,
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T07:58:16Z",
|
||||
"consumption_period_start": "0001-01-01T00:00:00Z",
|
||||
"consumption_period_end": "0001-01-01T00:00:00Z",
|
||||
"owner_id": "org-royal-sun-91776391",
|
||||
"org_id": "org-royal-sun-91776391"
|
||||
},
|
||||
"connection_uris": [
|
||||
{
|
||||
"connection_uri": "postgresql://neondb_owner:npg_N67FDMtGvJke@ep-round-unit-afbn7qv4.c-2.us-west-2.aws.neon.tech/neondb?sslmode=require",
|
||||
"connection_parameters": {
|
||||
"database": "neondb",
|
||||
"password": "npg_N67FDMtGvJke",
|
||||
"role": "neondb_owner",
|
||||
"host": "ep-round-unit-afbn7qv4.c-2.us-west-2.aws.neon.tech",
|
||||
"pooler_host": "ep-round-unit-afbn7qv4-pooler.c-2.us-west-2.aws.neon.tech"
|
||||
}
|
||||
}
|
||||
],
|
||||
"roles": [
|
||||
{
|
||||
"branch_id": "br-green-mode-afe3fl9y",
|
||||
"name": "neondb_owner",
|
||||
"password": "npg_N67FDMtGvJke",
|
||||
"protected": false,
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T07:58:16Z"
|
||||
}
|
||||
],
|
||||
"databases": [
|
||||
{
|
||||
"id": 6677853,
|
||||
"branch_id": "br-green-mode-afe3fl9y",
|
||||
"name": "neondb",
|
||||
"owner_name": "neondb_owner",
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T07:58:16Z"
|
||||
}
|
||||
],
|
||||
"operations": [
|
||||
{
|
||||
"id": "08b9367d-6918-4cd5-b4a6-41c8fd984b7e",
|
||||
"project_id": "sparkling-hill-99143322",
|
||||
"branch_id": "br-green-mode-afe3fl9y",
|
||||
"action": "create_timeline",
|
||||
"status": "running",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T07:58:16Z",
|
||||
"total_duration_ms": 0
|
||||
},
|
||||
{
|
||||
"id": "c6917f04-5cd3-48a2-97c9-186b1d9729f0",
|
||||
"project_id": "sparkling-hill-99143322",
|
||||
"branch_id": "br-green-mode-afe3fl9y",
|
||||
"endpoint_id": "ep-round-unit-afbn7qv4",
|
||||
"action": "start_compute",
|
||||
"status": "scheduling",
|
||||
"failures_count": 0,
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T07:58:16Z",
|
||||
"total_duration_ms": 0
|
||||
}
|
||||
],
|
||||
"branch": {
|
||||
"id": "br-green-mode-afe3fl9y",
|
||||
"project_id": "sparkling-hill-99143322",
|
||||
"name": "main",
|
||||
"current_state": "init",
|
||||
"pending_state": "ready",
|
||||
"state_changed_at": "2025-09-10T07:58:16Z",
|
||||
"creation_source": "console",
|
||||
"primary": true,
|
||||
"default": true,
|
||||
"protected": false,
|
||||
"cpu_used_sec": 0,
|
||||
"compute_time_seconds": 0,
|
||||
"active_time_seconds": 0,
|
||||
"written_data_bytes": 0,
|
||||
"data_transfer_bytes": 0,
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T07:58:16Z",
|
||||
"init_source": "parent-data"
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"host": "ep-round-unit-afbn7qv4.c-2.us-west-2.aws.neon.tech",
|
||||
"id": "ep-round-unit-afbn7qv4",
|
||||
"project_id": "sparkling-hill-99143322",
|
||||
"branch_id": "br-green-mode-afe3fl9y",
|
||||
"autoscaling_limit_min_cu": 0.25,
|
||||
"autoscaling_limit_max_cu": 0.25,
|
||||
"region_id": "aws-us-west-2",
|
||||
"type": "read_write",
|
||||
"current_state": "init",
|
||||
"pending_state": "active",
|
||||
"settings": {},
|
||||
"pooler_enabled": false,
|
||||
"pooler_mode": "transaction",
|
||||
"disabled": false,
|
||||
"passwordless_access": true,
|
||||
"creation_source": "console",
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T07:58:16Z",
|
||||
"proxy_host": "c-2.us-west-2.aws.neon.tech",
|
||||
"suspend_timeout_seconds": 0,
|
||||
"provisioner": "k8s-neonvm"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Retrieve project details
|
||||
|
||||
1. Action: Retrieves detailed information about a single, specific project.
|
||||
2. Endpoint: `GET /projects/{project_id}`
|
||||
3. Prerequisite: You must have the `project_id` of the project you wish to retrieve.
|
||||
4. Path Parameters:
|
||||
- `project_id` (required, string): The unique identifier of the project.
|
||||
|
||||
Example request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/sparkling-hill-99143322' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"project": {
|
||||
"data_storage_bytes_hour": 0,
|
||||
"data_transfer_bytes": 0,
|
||||
"written_data_bytes": 0,
|
||||
"compute_time_seconds": 0,
|
||||
"active_time_seconds": 0,
|
||||
"cpu_used_sec": 0,
|
||||
"id": "sparkling-hill-99143322",
|
||||
"platform_id": "aws",
|
||||
"region_id": "aws-us-west-2",
|
||||
"name": "my-new-api-project",
|
||||
"provisioner": "k8s-neonvm",
|
||||
"default_endpoint_settings": {
|
||||
"autoscaling_limit_min_cu": 0.25,
|
||||
"autoscaling_limit_max_cu": 0.25,
|
||||
"suspend_timeout_seconds": 0
|
||||
},
|
||||
"settings": {
|
||||
"allowed_ips": {
|
||||
"ips": [],
|
||||
"protected_branches_only": false
|
||||
},
|
||||
"enable_logical_replication": false,
|
||||
"maintenance_window": {
|
||||
"weekdays": [5],
|
||||
"start_time": "07:00",
|
||||
"end_time": "08:00"
|
||||
},
|
||||
"block_public_connections": false,
|
||||
"block_vpc_connections": false,
|
||||
"hipaa": false
|
||||
},
|
||||
"pg_version": 17,
|
||||
"proxy_host": "c-2.us-west-2.aws.neon.tech",
|
||||
"branch_logical_size_limit": 512,
|
||||
"branch_logical_size_limit_bytes": 536870912,
|
||||
"store_passwords": true,
|
||||
"creation_source": "console",
|
||||
"history_retention_seconds": 86400,
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T07:58:25Z",
|
||||
"synthetic_storage_size": 0,
|
||||
"consumption_period_start": "2025-09-10T06:58:15Z",
|
||||
"consumption_period_end": "2025-10-01T00:00:00Z",
|
||||
"owner_id": "org-royal-sun-91776391",
|
||||
"owner": {
|
||||
"email": "<USER_EMAIL>",
|
||||
"name": "My Personal Account",
|
||||
"branches_limit": 10,
|
||||
"subscription_type": "free_v3"
|
||||
},
|
||||
"compute_last_active_at": "2025-09-10T07:58:21Z",
|
||||
"org_id": "org-royal-sun-91776391"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Update a project
|
||||
|
||||
1. Action: Updates the settings of a specified project. This endpoint is used to modify a wide range of project attributes after creation, such as its name, default compute settings, security policies, and maintenance schedules.
|
||||
2. Endpoint: `PATCH /projects/{project_id}`
|
||||
3. Path Parameters:
|
||||
- `project_id` (string, required): The unique identifier of the project to update.
|
||||
4. Body Parameters: The request body must contain a top-level `project` object with the attributes to be updated.
|
||||
|
||||
`project` (object, required): The main container for the settings you want to modify.
|
||||
- `name` (string, optional): A new descriptive name for the project.
|
||||
- `history_retention_seconds` (integer, optional): The duration in seconds (0 to 2,592,000) to retain project history.
|
||||
- `default_endpoint_settings` (object, optional): New default settings for compute endpoints created in this project.
|
||||
- `autoscaling_limit_min_cu` (number, optional): The minimum number of Compute Units (CU). Minimum `0.25`.
|
||||
- `autoscaling_limit_max_cu` (number, optional): The maximum number of Compute Units (CU). Minimum `0.25`.
|
||||
- `suspend_timeout_seconds` (integer, optional): Duration of inactivity in seconds before a compute is suspended. Ranges from -1 (never suspend) to 604800 (1 week). A value of `0` uses the default of 300 seconds (5 minutes).
|
||||
- `settings` (object, optional): Project-wide settings to update.
|
||||
- `quota` (object, optional): Per-project consumption quotas.
|
||||
- `active_time_seconds` (integer, optional): Wall-clock time allowance for active computes.
|
||||
- `compute_time_seconds` (integer, optional): CPU seconds allowance.
|
||||
- `written_data_bytes` (integer, optional): Data written allowance.
|
||||
- `data_transfer_bytes` (integer, optional): Data transferred allowance.
|
||||
- `logical_size_bytes` (integer, optional): Logical data size limit per branch.
|
||||
- `allowed_ips` (object, optional): Modifies the IP Allowlist.
|
||||
- `ips` (array of strings, optional): The new list of allowed IP addresses or CIDR ranges.
|
||||
- `protected_branches_only` (boolean, optional): If `true`, the IP allowlist applies only to protected branches.
|
||||
- `enable_logical_replication` (boolean, optional): Sets `wal_level=logical`. This is irreversible.
|
||||
- `maintenance_window` (object, optional): The time period for scheduled maintenance.
|
||||
- `weekdays` (array of integers, required if `maintenance_window` is set): Days of the week (1=Monday, 7=Sunday).
|
||||
- `start_time` (string, required if `maintenance_window` is set): Start time in "HH:MM" UTC format.
|
||||
- `end_time` (string, required if `maintenance_window` is set): End time in "HH:MM" UTC format.
|
||||
- `block_public_connections` (boolean, optional): If `true`, disallows connections from the public internet.
|
||||
- `block_vpc_connections` (boolean, optional): If `true`, disallows connections from VPC endpoints.
|
||||
- `audit_log_level` (string, optional): Sets the audit log level. Allowed values: `base`, `extended`, `full`.
|
||||
- `hipaa` (boolean, optional): Toggles HIPAA compliance settings.
|
||||
- `preload_libraries` (object, optional): Libraries to preload into compute instances.
|
||||
- `use_defaults` (boolean, optional): Toggles the use of default libraries.
|
||||
- `enabled_libraries` (array of strings, optional): A list of specific libraries to enable.
|
||||
|
||||
Example request
|
||||
|
||||
```bash
|
||||
curl -X PATCH 'https://console.neon.tech/api/v2/projects/sparkling-hill-99143322' \
|
||||
-H 'accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"project": {
|
||||
"name": "updated-project-name"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"project": {
|
||||
"data_storage_bytes_hour": 0,
|
||||
"data_transfer_bytes": 0,
|
||||
"written_data_bytes": 29060360,
|
||||
"compute_time_seconds": 79,
|
||||
"active_time_seconds": 308,
|
||||
"cpu_used_sec": 79,
|
||||
"id": "sparkling-hill-99143322",
|
||||
"platform_id": "aws",
|
||||
"region_id": "aws-us-west-2",
|
||||
"name": "updated-project-name",
|
||||
"provisioner": "k8s-neonvm",
|
||||
"default_endpoint_settings": {
|
||||
"autoscaling_limit_min_cu": 0.25,
|
||||
"autoscaling_limit_max_cu": 0.25,
|
||||
"suspend_timeout_seconds": 0
|
||||
},
|
||||
"settings": {
|
||||
"allowed_ips": {
|
||||
"ips": [],
|
||||
"protected_branches_only": false
|
||||
},
|
||||
"enable_logical_replication": false,
|
||||
"maintenance_window": {
|
||||
"weekdays": [5],
|
||||
"start_time": "07:00",
|
||||
"end_time": "08:00"
|
||||
},
|
||||
"block_public_connections": false,
|
||||
"block_vpc_connections": false,
|
||||
"hipaa": false
|
||||
},
|
||||
"pg_version": 17,
|
||||
"proxy_host": "c-2.us-west-2.aws.neon.tech",
|
||||
"branch_logical_size_limit": 512,
|
||||
"branch_logical_size_limit_bytes": 536870912,
|
||||
"store_passwords": true,
|
||||
"creation_source": "console",
|
||||
"history_retention_seconds": 86400,
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T08:08:23Z",
|
||||
"synthetic_storage_size": 0,
|
||||
"consumption_period_start": "0001-01-01T00:00:00Z",
|
||||
"consumption_period_end": "0001-01-01T00:00:00Z",
|
||||
"owner_id": "org-royal-sun-91776391",
|
||||
"compute_last_active_at": "2025-09-10T07:58:21Z"
|
||||
},
|
||||
"operations": []
|
||||
}
|
||||
```
|
||||
|
||||
### Delete project
|
||||
|
||||
1. Action: Permanently deletes a project and all of its associated resources, including all branches, computes, databases, and roles.
|
||||
2. Endpoint: `DELETE /projects/{project_id}`
|
||||
3. Prerequisite: You must have the `project_id` of the project you wish to delete.
|
||||
4. Warning: This is a destructive action that cannot be undone. It deletes all data, databases, and resources in the project. Proceed with extreme caution and confirm with the user before executing this operation.
|
||||
5. Path Parameters:
|
||||
- `project_id` (required, string): The unique identifier of the project to be deleted.
|
||||
|
||||
Example request:
|
||||
|
||||
```bash
|
||||
curl -X 'DELETE' \
|
||||
'https://console.neon.tech/api/v2/projects/sparkling-hill-99143322' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"project": {
|
||||
"data_storage_bytes_hour": 0,
|
||||
"data_transfer_bytes": 0,
|
||||
"written_data_bytes": 29060360,
|
||||
"compute_time_seconds": 79,
|
||||
"active_time_seconds": 308,
|
||||
"cpu_used_sec": 79,
|
||||
"id": "sparkling-hill-99143322",
|
||||
"platform_id": "aws",
|
||||
"region_id": "aws-us-west-2",
|
||||
"name": "updated-project-name",
|
||||
"provisioner": "k8s-neonvm",
|
||||
"default_endpoint_settings": {
|
||||
"autoscaling_limit_min_cu": 0.25,
|
||||
"autoscaling_limit_max_cu": 0.25,
|
||||
"suspend_timeout_seconds": 0
|
||||
},
|
||||
"settings": {
|
||||
"allowed_ips": {
|
||||
"ips": [],
|
||||
"protected_branches_only": false
|
||||
},
|
||||
"enable_logical_replication": false,
|
||||
"maintenance_window": {
|
||||
"weekdays": [5],
|
||||
"start_time": "07:00",
|
||||
"end_time": "08:00"
|
||||
},
|
||||
"block_public_connections": false,
|
||||
"block_vpc_connections": false,
|
||||
"hipaa": false
|
||||
},
|
||||
"pg_version": 17,
|
||||
"proxy_host": "c-2.us-west-2.aws.neon.tech",
|
||||
"branch_logical_size_limit": 512,
|
||||
"branch_logical_size_limit_bytes": 536870912,
|
||||
"store_passwords": true,
|
||||
"creation_source": "console",
|
||||
"history_retention_seconds": 86400,
|
||||
"created_at": "2025-09-10T07:58:16Z",
|
||||
"updated_at": "2025-09-10T08:08:23Z",
|
||||
"synthetic_storage_size": 0,
|
||||
"consumption_period_start": "0001-01-01T00:00:00Z",
|
||||
"consumption_period_end": "0001-01-01T00:00:00Z",
|
||||
"owner_id": "org-royal-sun-91776391",
|
||||
"compute_last_active_at": "2025-09-10T07:58:21Z",
|
||||
"org_id": "org-royal-sun-91776391"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Retrieve connection URI
|
||||
|
||||
1. Action: Retrieves a ready-to-use connection URI for a specific database within a project.
|
||||
2. Endpoint: `GET /projects/{project_id}/connection_uri`
|
||||
3. Prerequisites: You must know the `project_id`, `database_name`, and `role_name`.
|
||||
4. Query Parameters:
|
||||
- `project_id` (path, required): The unique identifier of the project.
|
||||
- `database_name` (query, required): The name of the target database.
|
||||
- `role_name` (query, required): The role to use for the connection.
|
||||
- `branch_id` (query, optional): The branch ID. Defaults to the project's primary branch if not specified.
|
||||
- `pooled` (query, optional, boolean): If set to `false`, returns a direct connection URI instead of a pooled one. Defaults to `true`.
|
||||
- `endpoint_id` (query, optional): The specific endpoint ID to connect to. Defaults to the `read-write` endpoint_id associated with the `branch_id` if not specified.
|
||||
|
||||
Example request:
|
||||
|
||||
```bash
|
||||
curl 'https://console.neon.tech/api/v2/projects/old-fire-32990194/connection_uri?database_name=neondb&role_name=neondb_owner' \
|
||||
-H 'Accept: application/json' \
|
||||
-H "Authorization: Bearer $NEON_API_KEY"
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"uri": "postgresql://neondb_owner:npg_IDNnorOST71P@ep-shiny-morning-a1bfdvjs-pooler.ap-southeast-1.aws.neon.tech/neondb?channel_binding=require&sslmode=require"
|
||||
}
|
||||
```
|
||||
254
neon-postgres/references/neon-serverless.md
Normal file
254
neon-postgres/references/neon-serverless.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Neon Serverless Driver
|
||||
|
||||
Patterns and best practices for connecting to Neon databases in serverless environments using the `@neondatabase/serverless` driver. The driver connects over **HTTP** for fast, single queries or **WebSockets** for `node-postgres` compatibility and interactive transactions.
|
||||
|
||||
For official documentation:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/serverless/serverless-driver
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Using npm
|
||||
npm install @neondatabase/serverless
|
||||
|
||||
# Using JSR
|
||||
bunx jsr add @neon/serverless
|
||||
```
|
||||
|
||||
**Note:** Version 1.0.0+ requires **Node.js v19 or later**.
|
||||
|
||||
For projects that depend on `pg` but want to use Neon's WebSocket-based connection pool:
|
||||
|
||||
```json
|
||||
"dependencies": {
|
||||
"pg": "npm:@neondatabase/serverless@^0.10.4"
|
||||
},
|
||||
"overrides": {
|
||||
"pg": "npm:@neondatabase/serverless@^0.10.4"
|
||||
}
|
||||
```
|
||||
|
||||
## Connection String
|
||||
|
||||
Always use environment variables:
|
||||
|
||||
```typescript
|
||||
// For HTTP queries
|
||||
import { neon } from "@neondatabase/serverless";
|
||||
const sql = neon(process.env.DATABASE_URL!);
|
||||
|
||||
// For WebSocket connections
|
||||
import { Pool } from "@neondatabase/serverless";
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
|
||||
```
|
||||
|
||||
**Never hardcode credentials:**
|
||||
|
||||
```typescript
|
||||
// AVOID
|
||||
const sql = neon("postgres://username:password@host.neon.tech/neondb");
|
||||
```
|
||||
|
||||
## HTTP Queries with `neon` function
|
||||
|
||||
Ideal for simple, "one-shot" queries in serverless/edge environments. Uses HTTP `fetch` - fastest method for single queries.
|
||||
|
||||
### Parameterized Queries
|
||||
|
||||
Use tagged template literals for safe parameter interpolation:
|
||||
|
||||
```typescript
|
||||
const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
|
||||
```
|
||||
|
||||
For manually constructed queries:
|
||||
|
||||
```typescript
|
||||
const [post] = await sql.query("SELECT * FROM posts WHERE id = $1", [postId]);
|
||||
```
|
||||
|
||||
**Never concatenate user input:**
|
||||
|
||||
```typescript
|
||||
// AVOID: SQL Injection Risk
|
||||
const [post] = await sql("SELECT * FROM posts WHERE id = " + postId);
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
```typescript
|
||||
// Return rows as arrays instead of objects
|
||||
const sqlArrayMode = neon(process.env.DATABASE_URL!, { arrayMode: true });
|
||||
const rows = await sqlArrayMode`SELECT id, title FROM posts`;
|
||||
// rows -> [[1, "First Post"], [2, "Second Post"]]
|
||||
|
||||
// Get full results including row count and field metadata
|
||||
const sqlFull = neon(process.env.DATABASE_URL!, { fullResults: true });
|
||||
const result = await sqlFull`SELECT * FROM posts LIMIT 1`;
|
||||
// result -> { rows: [...], fields: [...], rowCount: 1, ... }
|
||||
```
|
||||
|
||||
## WebSocket Connections with `Pool` and `Client`
|
||||
|
||||
Use for `node-postgres` compatibility, interactive transactions, or session support.
|
||||
|
||||
### WebSocket Configuration
|
||||
|
||||
For Node.js v21 and earlier:
|
||||
|
||||
```typescript
|
||||
import { Pool, neonConfig } from "@neondatabase/serverless";
|
||||
import ws from "ws";
|
||||
|
||||
// Required for Node.js < v22
|
||||
neonConfig.webSocketConstructor = ws;
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
|
||||
```
|
||||
|
||||
### Serverless Lifecycle Management
|
||||
|
||||
Create, use, and close the pool within the same invocation:
|
||||
|
||||
```typescript
|
||||
// Vercel Edge Functions example
|
||||
export default async (req: Request, ctx: ExecutionContext) => {
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
|
||||
|
||||
try {
|
||||
const { rows } = await pool.query("SELECT * FROM users");
|
||||
return new Response(JSON.stringify(rows));
|
||||
} catch (err) {
|
||||
console.error(err);
|
||||
return new Response("Database error", { status: 500 });
|
||||
} finally {
|
||||
ctx.waitUntil(pool.end());
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
**Avoid** creating a global `Pool` instance outside the handler.
|
||||
|
||||
## Transactions
|
||||
|
||||
### HTTP Transactions
|
||||
|
||||
For running multiple queries in a single, non-interactive transaction:
|
||||
|
||||
```typescript
|
||||
const [newUser, newProfile] = await sql.transaction(
|
||||
[
|
||||
sql`INSERT INTO users(name) VALUES(${name}) RETURNING id`,
|
||||
sql`INSERT INTO profiles(user_id, bio) VALUES(${userId}, ${bio})`,
|
||||
],
|
||||
{
|
||||
isolationLevel: "ReadCommitted",
|
||||
readOnly: false,
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
### Interactive Transactions
|
||||
|
||||
For complex transactions with conditional logic:
|
||||
|
||||
```typescript
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
|
||||
const client = await pool.connect();
|
||||
try {
|
||||
await client.query("BEGIN");
|
||||
const {
|
||||
rows: [{ id }],
|
||||
} = await client.query("INSERT INTO users(name) VALUES($1) RETURNING id", [
|
||||
name,
|
||||
]);
|
||||
await client.query("INSERT INTO profiles(user_id, bio) VALUES($1, $2)", [
|
||||
id,
|
||||
bio,
|
||||
]);
|
||||
await client.query("COMMIT");
|
||||
} catch (err) {
|
||||
await client.query("ROLLBACK");
|
||||
throw err;
|
||||
} finally {
|
||||
client.release();
|
||||
await pool.end();
|
||||
}
|
||||
```
|
||||
|
||||
## Environment-Specific Optimizations
|
||||
|
||||
```javascript
|
||||
// For Vercel Edge Functions, specify nearest region
|
||||
export const config = {
|
||||
runtime: "edge",
|
||||
regions: ["iad1"], // Region nearest to your Neon DB
|
||||
};
|
||||
|
||||
// For Cloudflare Workers, consider using Hyperdrive
|
||||
// https://neon.com/blog/hyperdrive-neon-faq
|
||||
```
|
||||
|
||||
## ORM Integration
|
||||
|
||||
For Drizzle ORM integration with the serverless driver, see `neon-drizzle.md`.
|
||||
|
||||
### Prisma
|
||||
|
||||
```typescript
|
||||
import { neonConfig } from "@neondatabase/serverless";
|
||||
import { PrismaNeon, PrismaNeonHTTP } from "@prisma/adapter-neon";
|
||||
import { PrismaClient } from "@prisma/client";
|
||||
import ws from "ws";
|
||||
|
||||
const connectionString = process.env.DATABASE_URL;
|
||||
neonConfig.webSocketConstructor = ws;
|
||||
|
||||
// HTTP adapter
|
||||
const adapterHttp = new PrismaNeonHTTP(connectionString!, {});
|
||||
export const prismaClientHttp = new PrismaClient({ adapter: adapterHttp });
|
||||
|
||||
// WebSocket adapter
|
||||
const adapterWs = new PrismaNeon({ connectionString });
|
||||
export const prismaClientWs = new PrismaClient({ adapter: adapterWs });
|
||||
```
|
||||
|
||||
### Kysely
|
||||
|
||||
```typescript
|
||||
import { Pool } from "@neondatabase/serverless";
|
||||
import { Kysely, PostgresDialect } from "kysely";
|
||||
|
||||
const dialect = new PostgresDialect({
|
||||
pool: new Pool({ connectionString: process.env.DATABASE_URL }),
|
||||
});
|
||||
|
||||
const db = new Kysely({ dialect });
|
||||
```
|
||||
|
||||
**NOTE:** Do not pass the `neon()` function to ORMs that expect a `node-postgres` compatible `Pool`.
|
||||
|
||||
## Error Handling
|
||||
|
||||
```javascript
|
||||
// Pool error handling
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
|
||||
pool.on("error", (err) => {
|
||||
console.error("Unexpected error on idle client", err);
|
||||
process.exit(-1);
|
||||
});
|
||||
|
||||
// Query error handling
|
||||
try {
|
||||
const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
|
||||
if (!post) {
|
||||
return new Response("Not found", { status: 404 });
|
||||
}
|
||||
} catch (err) {
|
||||
console.error("Database query failed:", err);
|
||||
return new Response("Server error", { status: 500 });
|
||||
}
|
||||
```
|
||||
334
neon-postgres/references/neon-typescript-sdk.md
Normal file
334
neon-postgres/references/neon-typescript-sdk.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Neon TypeScript SDK
|
||||
|
||||
The `@neondatabase/api-client` TypeScript SDK is a typed wrapper around the Neon REST API. It provides methods for managing all Neon resources, including projects, branches, endpoints, roles, and databases.
|
||||
|
||||
For core concepts (Organization, Project, Branch, Endpoint, etc.), see `what-is-neon.md`.
|
||||
|
||||
## Documentation
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/typescript-sdk
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @neondatabase/api-client
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
```typescript
|
||||
import { createApiClient } from "@neondatabase/api-client";
|
||||
|
||||
const apiKey = process.env.NEON_API_KEY;
|
||||
if (!apiKey) {
|
||||
throw new Error("NEON_API_KEY environment variable is not set.");
|
||||
}
|
||||
|
||||
const apiClient = createApiClient({ apiKey });
|
||||
```
|
||||
|
||||
## Projects
|
||||
|
||||
### List Projects
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.listProjects({});
|
||||
console.log("Projects:", response.data.projects);
|
||||
```
|
||||
|
||||
### Create Project
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.createProject({
|
||||
project: { name: "my-project", pg_version: 17, region_id: "aws-us-east-2" },
|
||||
});
|
||||
console.log(
|
||||
"Connection URI:",
|
||||
response.data.connection_uris[0]?.connection_uri,
|
||||
);
|
||||
```
|
||||
|
||||
### Get Project
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.getProject("your-project-id");
|
||||
```
|
||||
|
||||
### Update Project
|
||||
|
||||
```typescript
|
||||
await apiClient.updateProject("your-project-id", {
|
||||
project: { name: "new-name" },
|
||||
});
|
||||
```
|
||||
|
||||
### Delete Project
|
||||
|
||||
```typescript
|
||||
await apiClient.deleteProject("project-id");
|
||||
```
|
||||
|
||||
### Get Connection URI
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.getConnectionUri({
|
||||
projectId: "your-project-id",
|
||||
database_name: "neondb",
|
||||
role_name: "neondb_owner",
|
||||
pooled: true,
|
||||
});
|
||||
console.log("URI:", response.data.uri);
|
||||
```
|
||||
|
||||
## Branches
|
||||
|
||||
### Create Branch
|
||||
|
||||
```typescript
|
||||
import { EndpointType } from "@neondatabase/api-client";
|
||||
|
||||
const response = await apiClient.createProjectBranch("your-project-id", {
|
||||
branch: { name: "feature-branch" },
|
||||
endpoints: [{ type: EndpointType.ReadWrite, autoscaling_limit_max_cu: 1 }],
|
||||
});
|
||||
```
|
||||
|
||||
### List Branches
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.listProjectBranches({
|
||||
projectId: "your-project-id",
|
||||
});
|
||||
```
|
||||
|
||||
### Get Branch
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.getProjectBranch("your-project-id", "br-xxx");
|
||||
```
|
||||
|
||||
### Update Branch
|
||||
|
||||
```typescript
|
||||
await apiClient.updateProjectBranch("your-project-id", "br-xxx", {
|
||||
branch: { name: "updated-name" },
|
||||
});
|
||||
```
|
||||
|
||||
### Delete Branch
|
||||
|
||||
```typescript
|
||||
await apiClient.deleteProjectBranch("your-project-id", "br-xxx");
|
||||
```
|
||||
|
||||
## Databases
|
||||
|
||||
### Create Database
|
||||
|
||||
```typescript
|
||||
await apiClient.createProjectBranchDatabase("your-project-id", "br-xxx", {
|
||||
database: { name: "my-app-db", owner_name: "neondb_owner" },
|
||||
});
|
||||
```
|
||||
|
||||
### List Databases
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.listProjectBranchDatabases(
|
||||
"your-project-id",
|
||||
"br-xxx",
|
||||
);
|
||||
```
|
||||
|
||||
### Delete Database
|
||||
|
||||
```typescript
|
||||
await apiClient.deleteProjectBranchDatabase(
|
||||
"your-project-id",
|
||||
"br-xxx",
|
||||
"my-app-db",
|
||||
);
|
||||
```
|
||||
|
||||
## Roles
|
||||
|
||||
### Create Role
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.createProjectBranchRole(
|
||||
"your-project-id",
|
||||
"br-xxx",
|
||||
{
|
||||
role: { name: "app_user" },
|
||||
},
|
||||
);
|
||||
console.log("Password:", response.data.role.password);
|
||||
```
|
||||
|
||||
### List Roles
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.listProjectBranchRoles(
|
||||
"your-project-id",
|
||||
"br-xxx",
|
||||
);
|
||||
```
|
||||
|
||||
### Delete Role
|
||||
|
||||
```typescript
|
||||
await apiClient.deleteProjectBranchRole(
|
||||
"your-project-id",
|
||||
"br-xxx",
|
||||
"app_user",
|
||||
);
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Create Endpoint
|
||||
|
||||
```typescript
|
||||
import { EndpointType } from "@neondatabase/api-client";
|
||||
|
||||
const response = await apiClient.createProjectEndpoint("your-project-id", {
|
||||
endpoint: { branch_id: "br-xxx", type: EndpointType.ReadOnly },
|
||||
});
|
||||
```
|
||||
|
||||
### List Endpoints
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.listProjectEndpoints("your-project-id");
|
||||
```
|
||||
|
||||
### Start/Suspend/Restart Endpoint
|
||||
|
||||
```typescript
|
||||
// Start
|
||||
await apiClient.startProjectEndpoint("your-project-id", "ep-xxx");
|
||||
|
||||
// Suspend
|
||||
await apiClient.suspendProjectEndpoint("your-project-id", "ep-xxx");
|
||||
|
||||
// Restart
|
||||
await apiClient.restartProjectEndpoint("your-project-id", "ep-xxx");
|
||||
```
|
||||
|
||||
### Update Endpoint
|
||||
|
||||
```typescript
|
||||
await apiClient.updateProjectEndpoint("your-project-id", "ep-xxx", {
|
||||
endpoint: { autoscaling_limit_max_cu: 2 },
|
||||
});
|
||||
```
|
||||
|
||||
### Delete Endpoint
|
||||
|
||||
```typescript
|
||||
await apiClient.deleteProjectEndpoint("your-project-id", "ep-xxx");
|
||||
```
|
||||
|
||||
## API Keys
|
||||
|
||||
### List API Keys
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.listApiKeys();
|
||||
```
|
||||
|
||||
### Create API Key
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.createApiKey({ key_name: "my-script-key" });
|
||||
console.log("Key:", response.data.key); // Store securely!
|
||||
```
|
||||
|
||||
### Revoke API Key
|
||||
|
||||
```typescript
|
||||
await apiClient.revokeApiKey(1234);
|
||||
```
|
||||
|
||||
## Operations
|
||||
|
||||
### List Operations
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.listProjectOperations({
|
||||
projectId: "your-project-id",
|
||||
});
|
||||
```
|
||||
|
||||
### Get Operation
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.getProjectOperation(
|
||||
"your-project-id",
|
||||
"op-xxx",
|
||||
);
|
||||
```
|
||||
|
||||
## Organizations
|
||||
|
||||
### Get Organization
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.getOrganization("org-xxx");
|
||||
```
|
||||
|
||||
### List Members
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.getOrganizationMembers("org-xxx");
|
||||
```
|
||||
|
||||
### Create Org API Key
|
||||
|
||||
```typescript
|
||||
const response = await apiClient.createOrgApiKey("org-xxx", {
|
||||
key_name: "ci-key",
|
||||
project_id: "project-xxx", // Optional: scope to project
|
||||
});
|
||||
```
|
||||
|
||||
### Invite Member
|
||||
|
||||
```typescript
|
||||
import { MemberRole } from "@neondatabase/api-client";
|
||||
|
||||
await apiClient.createOrganizationInvitations("org-xxx", {
|
||||
invitations: [{ email: "dev@example.com", role: MemberRole.Member }],
|
||||
});
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```typescript
|
||||
async function safeApiOperation(projectId: string) {
|
||||
try {
|
||||
const response = await apiClient.getProject(projectId);
|
||||
return response.data;
|
||||
} catch (error: any) {
|
||||
if (error.isAxiosError) {
|
||||
const status = error.response?.status;
|
||||
switch (status) {
|
||||
case 401:
|
||||
console.error("Check your NEON_API_KEY");
|
||||
break;
|
||||
case 404:
|
||||
console.error("Resource not found");
|
||||
break;
|
||||
case 429:
|
||||
console.error("Rate limit exceeded");
|
||||
break;
|
||||
default:
|
||||
console.error("API error:", error.response?.data?.message);
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
78
neon-postgres/references/referencing-docs.md
Normal file
78
neon-postgres/references/referencing-docs.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# Referencing Neon Docs
|
||||
|
||||
The Neon documentation is the source of truth for all Neon-related information. Always verify Neon-related claims, configurations, and best practices against the official documentation.
|
||||
|
||||
## Getting the Documentation Index
|
||||
|
||||
To get a list of all available Neon documentation pages:
|
||||
|
||||
```bash
|
||||
curl https://neon.com/llms.txt
|
||||
```
|
||||
|
||||
This returns an index of all documentation pages with their URLs and descriptions.
|
||||
|
||||
## Fetching Individual Documentation Pages
|
||||
|
||||
To fetch any documentation page as markdown for review:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/<path>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Fetch the API reference
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/reference/api-reference
|
||||
|
||||
# Fetch connection pooling docs
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/connect/connection-pooling
|
||||
|
||||
# Fetch branching documentation
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching
|
||||
|
||||
# Fetch serverless driver docs
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/serverless/serverless-driver
|
||||
```
|
||||
|
||||
## Common Documentation Paths
|
||||
|
||||
| Topic | Path |
|
||||
| ------------------ | ------------------------------------ |
|
||||
| Introduction | `/docs/introduction` |
|
||||
| Branching | `/docs/introduction/branching` |
|
||||
| Autoscaling | `/docs/introduction/autoscaling` |
|
||||
| Scale to Zero | `/docs/introduction/scale-to-zero` |
|
||||
| Connection Pooling | `/docs/connect/connection-pooling` |
|
||||
| Serverless Driver | `/docs/serverless/serverless-driver` |
|
||||
| JavaScript SDK | `/docs/reference/javascript-sdk` |
|
||||
| API Reference | `/docs/reference/api-reference` |
|
||||
| TypeScript SDK | `/docs/reference/typescript-sdk` |
|
||||
| Python SDK | `/docs/reference/python-sdk` |
|
||||
|
||||
## Framework and Language Guides
|
||||
|
||||
```bash
|
||||
# Next.js
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/guides/nextjs
|
||||
|
||||
# Django
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/guides/django
|
||||
|
||||
# Drizzle ORM
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/guides/drizzle
|
||||
|
||||
# Prisma
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/guides/prisma
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always verify** - When answering questions about Neon features, APIs, or configurations, fetch the relevant documentation to verify your response is accurate.
|
||||
|
||||
2. **Check llms.txt first** - If you're unsure which documentation page covers a topic, fetch the llms.txt index to find the relevant URL. Don't make up URLs.
|
||||
|
||||
3. **Docs are the source of truth** - If there's any conflict between your training data and the documentation, the documentation is correct. Neon features and APIs evolve, so always defer to the current docs.
|
||||
|
||||
4. **Cite your sources** - When providing information from the docs, reference the documentation URL so users can read more if needed.
|
||||
57
neon-postgres/references/what-is-neon.md
Normal file
57
neon-postgres/references/what-is-neon.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# What is Neon
|
||||
|
||||
Neon is a serverless Postgres platform designed to help you build reliable and scalable applications faster. It separates compute and storage to offer modern developer features such as autoscaling, branching, instant restore, and scale-to-zero.
|
||||
|
||||
For the full introduction, fetch the official docs:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
Understanding Neon's resource hierarchy is essential for working with the platform effectively.
|
||||
|
||||
| Concept | Description | Key Relationship |
|
||||
| ---------------- | --------------------------------------------------------------------- | ------------------------- |
|
||||
| Organization | Highest-level container for billing, users, and projects | Contains Projects |
|
||||
| Project | Primary container for all database resources for an application | Contains Branches |
|
||||
| Branch | Lightweight, copy-on-write clone of database state | Contains Databases, Roles |
|
||||
| Compute Endpoint | Running PostgreSQL instance (CPU/RAM for queries) | Attached to a Branch |
|
||||
| Database | Logical container for data (tables, schemas, views) | Exists within a Branch |
|
||||
| Role | PostgreSQL role for authentication and authorization | Belongs to a Branch |
|
||||
| Operation | Async action by the control plane (creating branch, starting compute) | Associated with Project |
|
||||
|
||||
## Key Differentiators
|
||||
|
||||
1. **Serverless Architecture**: Compute scales automatically and can suspend when idle
|
||||
2. **Branching**: Create instant database copies without duplicating storage
|
||||
3. **Separation of Compute and Storage**: Pay for compute only when active
|
||||
4. **Postgres Compatible**: Works with any Postgres driver, ORM, or tool
|
||||
|
||||
## Documentation Resources
|
||||
|
||||
| Topic | Documentation URL |
|
||||
| ---------------------- | --------------------------------------------------------- |
|
||||
| Introduction | https://neon.com/docs/introduction |
|
||||
| Architecture | https://neon.com/docs/introduction/architecture-overview |
|
||||
| Plans & Billing | https://neon.com/docs/introduction/about-billing |
|
||||
| Regions | https://neon.com/docs/introduction/regions |
|
||||
| Postgres Compatibility | https://neon.com/docs/reference/compatibility |
|
||||
|
||||
```bash
|
||||
# Fetch architecture docs
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/architecture-overview
|
||||
|
||||
# Fetch plans and billing
|
||||
curl -H "Accept: text/markdown" https://neon.com/docs/introduction/about-billing
|
||||
```
|
||||
|
||||
## When to Use Neon
|
||||
|
||||
Neon is ideal for:
|
||||
|
||||
- **Serverless applications**: Functions that need database access without managing connections
|
||||
- **Development workflows**: Branch databases like code for isolated testing
|
||||
- **Variable workloads**: Auto-scale during traffic spikes, scale to zero when idle
|
||||
- **Cost optimization**: Pay only for active compute time and storage used
|
||||
Reference in New Issue
Block a user