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

# Homebrew (recommended)
brew install neonctl

# Or npm
npm i -g neonctl

2. Authenticate

# 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

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

Core Commands

Projects (top-level container)

# 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)

# 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

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

# Create database
neonctl databases create --project-id <project-id> --branch <branch-name> --name "mydb"

# Delete database
neonctl databases delete <db-name> --project-id <project-id> --branch <branch-name>

Connection Strings

# Get connection string (default branch)
neonctl connection-string --project-id <project-id>

# Get connection string for specific branch
neonctl connection-string <branch-name> --project-id <project-id>

# Pooled connection (recommended for serverless)
neonctl connection-string --project-id <project-id> --pooled

# Extended format (with all details)
neonctl connection-string --project-id <project-id> --extended

Roles (database users)

# List roles
neonctl roles list --project-id <project-id> --branch <branch-name>

# Create role
neonctl roles create --project-id <project-id> --branch <branch-name> --name "app_user"

Executing Queries

Using psql

# Get connection string and connect
neonctl connection-string --project-id <project-id> | xargs psql

# Or direct
psql "$(neonctl connection-string --project-id <project-id>)"

Using the connection string in code

# Get the string
CONNECTION_STRING=$(neonctl connection-string --project-id <project-id> --pooled)

# Use in any Postgres client
psql "$CONNECTION_STRING" -c "SELECT * FROM users LIMIT 5;"

Context (Avoid Repeating Project ID)

Set context to avoid passing --project-id every time:

# Set project context
neonctl set-context --project-id <project-id>

# Now commands use that project automatically
neonctl branches list
neonctl databases list
neonctl connection-string

Agent Workflow Examples

Create org database with branches

# Create project for org
neonctl projects create --name "website-org-db" -o json

# Create production branch (main is created by default)
# Create dev branch for testing
neonctl branches create --name "dev" --project-id <id>

# Get connection strings
neonctl connection-string main --project-id <id> --pooled  # for prod
neonctl connection-string dev --project-id <id> --pooled   # for dev

Create leads table

# Connect and create schema
psql "$(neonctl cs --project-id <id>)" <<EOF
CREATE TABLE leads (
    id SERIAL PRIMARY KEY,
    business_name VARCHAR(255) NOT NULL,
    category VARCHAR(100),
    location VARCHAR(255),
    phone VARCHAR(50),
    email VARCHAR(255),
    website VARCHAR(255),
    status VARCHAR(50) DEFAULT 'identified',
    priority VARCHAR(20) DEFAULT 'medium',
    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_leads_status ON leads(status);
CREATE INDEX idx_leads_category ON leads(category);
EOF

Branch for experiments

# Create a branch to test schema changes
neonctl branches create --name "schema-experiment" --project-id <id>

# Test your changes on the branch
psql "$(neonctl cs schema-experiment --project-id <id>)" -c "ALTER TABLE leads ADD COLUMN score INT;"

# If it works, apply to main. If not, just delete the branch
neonctl branches delete schema-experiment --project-id <id>

Output Formats

# JSON (for parsing)
neonctl projects list -o json

# YAML
neonctl projects list -o yaml

# Table (default, human-readable)
neonctl projects list -o table

Environment Variables

# API key (required if not using `neonctl auth`)
export NEON_API_KEY=your_key

# Default project (alternative to set-context)
export NEON_PROJECT_ID=your_project_id

Common Patterns

Check if neonctl is configured

neonctl me -o json 2>/dev/null && echo "Authenticated" || echo "Need to run: neonctl auth"

Quick database query

# One-liner query
psql "$(neonctl cs)" -c "SELECT COUNT(*) FROM leads WHERE status='contacted';"

Export to CSV

psql "$(neonctl cs)" -c "COPY (SELECT * FROM leads) TO STDOUT WITH CSV HEADER" > leads.csv

Import from CSV

psql "$(neonctl cs)" -c "\COPY leads(business_name,category,location) FROM 'import.csv' WITH CSV HEADER"

Troubleshooting

"Connection refused"

• Check if branch compute is active (scale-to-zero may have paused it)
• Use --pooled connection string for serverless workloads

"Permission denied"

• Verify API key: neonctl me
• Re-authenticate: neonctl auth

Slow first connection

• Normal for scale-to-zero. First connection wakes the compute (~1-2 seconds)
• Use connection pooling to maintain warm connections

Links

• Neon Console — Web dashboard
• API Docs — REST API reference
• CLI Reference — Full CLI docs
• GitHub — CLI source code