NeonDB-skill

Manage Neon serverless Postgres databases. Create projects, branches, databases, and execute queries. Perfect for agent workflows needing persistent storage with branching (like git for databases), scale-to-zero, and instant provisioning.

Security Scan

The skill mostly matches its stated purpose (driving neonctl) but contains inconsistencies and missing declarations (psql/jq/NEON_API_KEY) and prints connection strings that contain credentials — review before installing or running.

Purpose & Capability

The skill's name/description align with requiring neonctl and using Neon. However the included script and docs also use psql and jq (and implicitly rely on a Postgres client and JSON parser) but the registry metadata does not declare those binaries or any required environment variables. That mismatch is a sign of incomplete packaging.

Instruction Scope

SKILL.md instructs the agent to install neonctl, authenticate via neonctl auth or NEON_API_KEY, create projects/branches/databases, and run psql. The runtime script invokes neonctl, jq, and psql and prints the full connection string. Instructions therefore access and display secrets (DB connection strings and potentially API keys) and reference system tools not declared in metadata — the documentation gives the agent broad discretion to create resources and reveal credentials.

Install Mechanism

Installers use Homebrew and npm for the neonctl binary, both are standard package mechanisms and appropriate for installing a CLI. No arbitrary download URLs or archive extraction are used.

Credentials

The skill's docs require NEON_API_KEY or running neonctl auth, but requires.env in the registry is empty. The script outputs connection strings (which contain DB credentials). Requiring an API key and exposing connection strings is reasonable for a DB tool, but the missing declaration of these env vars and the fact that outputs include credentials are disproportionate without clearer guidance on storage/handling of keys.

Persistence & Privilege

The skill does not request always:true and does not claim persistent elevated privileges or self-modify other skills. Autonomous invocation is allowed (platform default), which is expected for useful skills.

What to consider before installing

This skill appears to do what it says (drive neonctl) but has gaps you should verify before use: 1) The package metadata omits required tools: ensure psql and jq are available where the agent runs, or the included script will fail. 2) The skill expects an API key (NEON_API_KEY) or interactive auth — consider the security of supplying that key to the agent; prefer ephemeral keys with limited scope and rotate them after testing. 3) The setup script prints full connection strings (credentials). Avoid pasting those into untrusted logs or allowing the agent to transmit them externally. 4) Confirm neonctl installation source (Homebrew or npm) in your environment policy. 5) If you want tighter control, run the setup script manually in an isolated environment, or request the publisher/source of the skill before granting access. If you want me to, I can produce a checklist or a hardened version of the setup script that avoids echoing credentials and verifies required binaries.

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