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?

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 
Get project details
neonctl projects get 

Branches (database snapshots)

# List branches
neonctl branches list --project-id 
Create branch (fork from main)
neonctl branches create --project-id  --name "dev-branch"
Create branch from specific point
neonctl branches create --project-id  --name "restore-test" --parent main --timestamp "2024-01-15T10:00:00Z"
Reset branch to parent
neonctl branches reset  --project-id  --parent
Delete branch
neonctl branches delete  --project-id 
Compare schemas
neonctl branches schema-diff --project-id  --base-branch main --compare-branch dev

Databases

# List databases
neonctl databases list --project-id  --branch 
Create database
neonctl databases create --project-id  --branch  --name "mydb"
Delete database
neonctl databases delete  --project-id  --branch 

Connection Strings

# Get connection string (default branch)
neonctl connection-string --project-id 
Get connection string for specific branch
neonctl connection-string  --project-id 
Pooled connection (recommended for serverless)
neonctl connection-string --project-id  --pooled
Extended format (with all details)
neonctl connection-string --project-id  --extended

Roles (database users)

# List roles
neonctl roles list --project-id  --branch 
Create role
neonctl roles create --project-id  --branch  --name "app_user"

Executing Queries

Using psql

# Get connection string and connect
neonctl connection-string --project-id  | xargs psql
Or direct
psql "$(neonctl connection-string --project-id )"

Using the connection string in code

# Get the string
CONNECTION_STRING=$(neonctl connection-string --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 
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 
Get connection strings
neonctl connection-string main --project-id  --pooled  # for prod
neonctl connection-string dev --project-id  --pooled   # for dev

Create leads table

# Connect and create schema
psql "$(neonctl cs --project-id )" <
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 
Test your changes on the branch
psql "$(neonctl cs schema-experiment --project-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 

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"

"Permission denied"

Slow first connection

Links

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"

"Connection refused"

"Permission denied"

Slow first connection