neondb

# NeonDB

Neon is **serverless Postgres** — scales to zero, branches like git, instant provisioning. Perfect for AI agents needing databases without ops overhead.

## Why Neon for Agents?

- **Instant databases** — Create in seconds, no server setup
- **Branching** — Fork your database like git (test without affecting prod)
- **Scale-to-zero** — Pay nothing when idle
- **Connection pooling** — Built-in, no PgBouncer needed
- **Generous free tier** — 0.5 GB storage, 190 compute hours/month

## Quick Start

### 1. Install CLI

```bash
# Homebrew (recommended)
brew install neonctl

# Or npm
npm i -g neonctl
```

### 2. Authenticate

```bash
# Interactive (opens browser)
neonctl auth

# Or with API key (get from console.neon.tech)
export NEON_API_KEY=your_api_key_here
```

### 3. Create Your First Project

```bash
neonctl projects create --name "my-agent-db"
```

## Core Commands

### Projects (top-level container)

```bash
# List all projects
neonctl projects list

# Create project
neonctl projects create --name "project-name"

# Delete project
neonctl projects delete <project-id>

# Get project details
neonctl projects get <project-id>
```

### Branches (database snapshots)

```bash
# List branches
neonctl branches list --project-id <project-id>

# Create branch (fork from main)
neonctl branches create --project-id <project-id> --name "dev-branch"

# Create branch from specific point
neonctl branches create --project-id <project-id> --name "restore-test" --parent main --timestamp "2024-01-15T10:00:00Z"

# Reset branch to parent
neonctl branches reset <branch-id> --project-id <project-id> --parent

# Delete branch
neonctl branches delete <branch-id> --project-id <project-id>

# Compare schemas
neonctl branches schema-diff --project-id <project-id> --base-branch main --compare-branch dev
```

### Databases

```bash
# List databases
neonctl databases list --project-id <project-id> --branch <branch-name>

# Create database
neonctl databases create --project-id <project-id...