neon

Neon

Three modes. Pick based on intent:

========================================

Branch mode — create, list, delete, or reset Neon branches

Create, list, and manage Neon database branches. Branches are instant copy-on-write snapshots — use them for safe experimentation, pre-migration testing, and disposable dev environments.

Connection Discovery

Before running any command, discover connection details:

1. Use the Read tool to read .env in the project root (and .env.local if it exists)
2. Look for these variables:
   • Database URL: DATABASE_URL, NEON_PROD_URL, NEON_DATABASE_URL, POSTGRES_URL, PG_URL, NEON_DEV_URL
   • Project config: NEON_PROJECT_ID, NEON_ORG_ID
   • API key (optional): NEON_API_KEY
3. If NEON_PROJECT_ID or NEON_ORG_ID is missing, ask the user
4. If NEON_API_KEY is found, include --api-key "<API_KEY>" in all neonctl commands. If not found, omit the flag entirely.

Store all discovered values and use them directly in commands — never use source .env.

Authentication

The neonctl CLI supports multiple auth methods. Try them in this order — stop at the first one that works:

Step 1: Check existing auth

With API key (if found in .env):

timeout 10 npx neonctl me --api-key "<API_KEY>"

Without API key:

timeout 10 npx neonctl me

• If output shows a table with Login/Email/Name — auth is good, proceed to Commands
• If output contains "Awaiting authentication" — auth is needed, continue to Step 2

Step 2: Try browser OAuth

Tell the user auth is needed, then run:

npx neonctl auth

This opens a browser window (60-second timeout). After auth completes, re-run the check from Step 1.

Step 3: If all else fails

Tell the user:

No valid Neon credentials found. Options:

1. Run npx neonctl auth to authenticate via browser
2. Create an API key at https://console.neon.tech/app/settings/api-keys and add NEON_API_KEY=<key> to .env

An API key enables fully headless operation (no browser needed).

Project Details

Project: foxxed
Project ID: morning-bonus-59275905 ($NEON_PROJECT_ID)
Org ID: org-ancient-base-30492340 ($NEON_ORG_ID)
Production branch: production (default, primary)
Development branch: development

Commands

All neonctl commands require --project-id and --org-id. Use the values discovered from .env.

In all examples below, include --api-key "<API_KEY>" only if NEON_API_KEY was found in .env. Otherwise omit that flag.

List Branches

npx neonctl branches list --project-id "<PROJECT_ID>" --org-id "<ORG_ID>"

Create Branch (from production)

npx neonctl branches create --project-id "<PROJECT_ID>" --org-id "<ORG_ID>" --name "<branch-name>" --output json

Name conventions:

• claude/<purpose> — for agent-created branches (e.g., claude/debug-supply-2026-02-12)
• dev/<feature> — for development work
• test/<description> — for testing

Create Branch at Point-in-Time

npx neonctl branches create --project-id "<PROJECT_ID>" --org-id "<ORG_ID>" --name "<branch-name>" --parent "production@2026-02-12T00:00:00Z" --output json

Note: Point-in-time branching is limited by the project's history retention window (currently ~6 hours for foxxed).

Get Connection String for Branch

npx neonctl connection-string "<branch-name>" --project-id "<PROJECT_ID>" --org-id "<ORG_ID>" --pooled --database-name foxxed --role-name neondb_owner

Then use the returned URL to query the branch:

psql "<BRANCH_URL>" -c "SELECT count(*) FROM addresses WHERE is_current = true;"

Delete Branch

npx neonctl branches delete "<branch-name>" --project-id "<PROJECT_ID>" --org-id "<ORG_ID>"

Always clean up agent-created branches when done.

Instructions

When the user asks to manage branches:

1. Discover connection details by reading .env (and .env.local) with the Read tool. Extract NEON_PROJECT_ID, NEON_ORG_ID, and optionally NEON_API_KEY.
2. Check auth — run the auth check from Step 1 above; if it fails, walk through the fallback chain
3. Execute the requested operation using the commands above, with all values inlined directly (no source .env, no shell variables)
4. For create operations, always report back the branch name and connection string
5. For destructive operations (delete), confirm with the user first unless it's a claude/* branch the agent created in this session

Workflow: Safe Experimentation

This workflow uses multiple separate commands. Run each as its own Bash call (do not chain with &&).

Step 1: Create a branch

npx neonctl branches create --project-id "<PROJECT_ID>" --org-id "<ORG_ID>" --name "claude/experiment-YYYYMMDD-HHMM" --output json

Step 2: Get connection string

npx neonctl connection-string "claude/experiment-..." --project-id "<PROJECT_ID>" --org-id "<ORG_ID>" --pooled --database-name foxxed --role-name neondb_owner

Step 3: Run experimental queries (read-write OK on branches)

psql "<BRANCH_URL>" -c "DELETE FROM label_proposals WHERE ..."

psql "<BRANCH_URL>" -c "UPDATE addresses SET ..."

Step 4: Clean up when done

npx neonctl branches delete "claude/experiment-..." --project-id "<PROJECT_ID>" --org-id "<ORG_ID>"

Limits

Neon free tier allows up to 10 branches. Check current branch count before creating new ones. Always delete claude/* branches when analysis is complete.

$ARGUMENTS

========================================

Info mode — connection overview: tables, sizes, branches

Quick database dashboard for Neon PostgreSQL. Shows connection status, table inventory, database size, and branch overview at a glance.

Connection Discovery

Before running any command, discover connection details:

1. Use the Read tool to read .env in the project root (and .env.local if it exists)
2. Look for a database URL variable. Check these names in order: DATABASE_URL, NEON_PROD_URL, NEON_DATABASE_URL, POSTGRES_URL, PG_URL, NEON_DEV_URL
3. Also look for: NEON_PROJECT_ID, NEON_ORG_ID, and NEON_API_KEY
4. If no database URL is found, ask the user for the connection string

Store all discovered values and use them directly in commands — never use source .env.

Instructions

1. Discover the connection URL and project details by reading .env (and .env.local) with the Read tool
2. Run the following commands and present the output in a clean, formatted summary

Step 1: Connection Test

pg_isready -d "<DB_URL>"

Step 2: Database Overview

psql "<DB_URL>" <<'EOF'
BEGIN TRANSACTION READ ONLY;

-- Database size
SELECT pg_size_pretty(pg_database_size(current_database())) AS database_size;

-- PostgreSQL version
SELECT version();

-- Table inventory: name, row count, total size
SELECT
    relname AS table_name,
    n_live_tup AS row_count,
    pg_size_pretty(pg_total_relation_size(relid)) AS total_size
FROM pg_stat_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

-- Active connections
SELECT count(*) AS active_connections FROM pg_stat_activity WHERE state = 'active';

COMMIT;
EOF

Step 3: Branch Overview (if neonctl auth is available)

Try to list branches. This step requires NEON_PROJECT_ID and NEON_ORG_ID from the .env file. If either is missing, skip this step.

If NEON_API_KEY was found in .env, include the --api-key flag. Otherwise omit it.

With API key:

timeout 10 npx neonctl branches list --project-id "<PROJECT_ID>" --org-id "<ORG_ID>" --api-key "<API_KEY>"

Without API key:

timeout 10 npx neonctl branches list --project-id "<PROJECT_ID>" --org-id "<ORG_ID>"

If the output contains "Awaiting authentication", skip and note "Branch listing: neonctl auth required".

Step 4: Present Results

Format the output as a summary:

## Neon Database Dashboard

**Connection:** [OK/FAILED]
**Database size:** [size]
**PostgreSQL version:** [version]
**Active connections:** [count]

### Tables
| Table | Rows | Size |
|-------|------|------|
| ...   | ...  | ...  |
| **Total** | **N** | **size** |

### Branches
| Name | State | Created |
|------|-------|---------|
| ...  | ...   | ...     |
(or "neonctl auth required — run `npx neonctl auth` to enable branch listing")

========================================

Query mode — run SQL queries, explore schema and data

Run ad-hoc SQL queries against Neon PostgreSQL databases using psql.

Connection Discovery

Before running any command, discover the database connection URL:

1. Use the Read tool to read .env in the project root (and .env.local if it exists)
2. Look for a database URL variable. Check these names in order: DATABASE_URL, NEON_PROD_URL, NEON_DATABASE_URL, POSTGRES_URL, PG_URL, NEON_DEV_URL
3. Use the first matching URL you find as the connection string for all subsequent commands
4. If no database URL is found, ask the user for the connection string

When the user says "dev database" or "development", look for variables containing DEV (e.g., NEON_DEV_URL, DATABASE_DEV_URL). Otherwise default to the first URL found (typically production).

Store the discovered URL and use it directly in all psql commands — never use source .env.

Usage

CRITICAL: All production queries MUST be wrapped in a read-only transaction:

psql "<DB_URL>" -c "BEGIN TRANSACTION READ ONLY; YOUR SQL HERE; COMMIT;"

For multi-line or complex queries, use a heredoc:

psql "<DB_URL>" <<'EOF'
BEGIN TRANSACTION READ ONLY;

SELECT
    schemaname,
    tablename,
    n_live_tup AS row_count
FROM pg_stat_user_tables
ORDER BY n_live_tup DESC
LIMIT 10;

COMMIT;
EOF

For development database (read-write allowed):

psql "<DB_URL>" -c "YOUR SQL HERE;"

Output Formats

• Default: psql table format
• --csv - CSV output
• -x - Expanded/vertical format (one column per line)
• -t - Tuples only (no headers/footers)
• -A - Unaligned output (useful with --csv)

Examples:

psql "<DB_URL>" --csv -c "BEGIN TRANSACTION READ ONLY; SELECT * FROM addresses WHERE is_current = true LIMIT 10; COMMIT;"

psql "<DB_URL>" -x -c "BEGIN TRANSACTION READ ONLY; SELECT * FROM addresses WHERE is_current = true LIMIT 1; COMMIT;"

Common Explorations

IMPORTANT: psql meta-commands (\dt, \d+, etc.) do NOT work with the -c flag when using a connection URL. Use heredoc or SQL equivalents instead.

List all tables with sizes:

psql "<DB_URL>" -c "BEGIN TRANSACTION READ ONLY;
SELECT
    relname AS table_name,
    n_live_tup AS row_count,
    pg_size_pretty(pg_total_relation_size(relid)) AS total_size
FROM pg_stat_user_tables
ORDER BY pg_total_relation_size(relid) DESC;
COMMIT;"

Describe a table (columns, types, nullability):

psql "<DB_URL>" -c "BEGIN TRANSACTION READ ONLY;
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema = 'public' AND table_name = 'addresses'
ORDER BY ordinal_position;
COMMIT;"

List indexes on a table:

psql "<DB_URL>" -c "BEGIN TRANSACTION READ ONLY;
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = 'addresses';
COMMIT;"

Sample data from a table:

psql "<DB_URL>" -c "BEGIN TRANSACTION READ ONLY; SELECT * FROM addresses WHERE is_current = true LIMIT 5; COMMIT;"

If you need psql meta-commands (\dt+, \d+ tablename, etc.), use heredoc:

psql "<DB_URL>" <<'EOF'
\dt+
EOF

Instructions

When the user asks to query Neon:

1. Discover the connection URL by reading .env (and .env.local if it exists) with the Read tool. Look for DATABASE_URL, NEON_PROD_URL, NEON_DATABASE_URL, POSTGRES_URL, PG_URL, or NEON_DEV_URL. If none found, ask the user.
2. Default to the production URL unless the user specifies dev
3. Always wrap production queries in BEGIN TRANSACTION READ ONLY; ... COMMIT;
4. Use SQL equivalents for schema inspection (not \dt, \d+) — meta-commands don't work with -c + URL
5. Run the psql command with the URL inlined directly (no source .env, no shell variables)
6. Present results clearly
7. Offer to refine or expand the query

$ARGUMENTS

========================================

Migration

Consolidated from legacy claudefather skills. Pick the mode based on intent.