NeonDB-skill

# 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> --branch <branch-name> --name "mydb"

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

Connection Strings

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

```bash # 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

```bash # 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

```bash # 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:

```bash # 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

```bash # 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

```bash # 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

```bash # 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

```bash # 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

```bash # 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

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

Quick database query

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

Export to CSV

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

Import from CSV

```bash 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