Neon CLI (neonctl)

--- name: Neon CLI (neonctl) description: Use this skill when you need to manage Neon PostgreSQL databases through the command line, including creating projects, managing branches, handling database connections, and performing database operations. metadata: author: skynet version: 1.0.0 category: infrastructure --- # Neon CLI (neonctl) Management ## Quick Start ```bash # Install neonctl npm install -g neonctl # Authenticate neonctl auth # List projects neonctl projects list # Create a new project neonctl projects create --name "my-app" ``` ## Core Commands ### Authentication & Setup ```bash # Interactive authentication neonctl auth # Set API key directly neonctl auth --api-key YOUR_API_KEY # Check current authentication status neonctl auth show ``` ### Project Management ```bash # List all projects neonctl projects list # Create new project neonctl projects create --name "production-db" --region us-east-1 # Get project details neonctl projects get PROJECT_ID # Delete project neonctl projects delete PROJECT_ID # Set default project neonctl set-context --project-id PROJECT_ID ``` ### Branch Operations ```bash # List branches neonctl branches list # Create branch from main neonctl branches create --name feature-branch # Create branch from specific parent neonctl branches create --name hotfix --parent-branch main # Create branch with specific compute settings neonctl branches create --name staging --compute-size small --suspend-timeout 3600 # Get branch details neonctl branches get BRANCH_ID # Delete branch neonctl branches delete BRANCH_ID # Reset branch to parent state neonctl branches reset BRANCH_ID ``` ### Database Management ```bash # List databases in current project neonctl databases list # Create database neonctl databases create myapp_db # Create database on specific branch neonctl databases create --branch-id BRANCH_ID production_db # Delete database neonctl databases delete myapp_db ``` ### Connection Management ```bash # Get connection string neonctl connection-string --database-name myapp_db # Get connection string for specific branch neonctl connection-string --branch-id BRANCH_ID --database-name myapp_db # Get pooled connection string neonctl connection-string --pooled --database-name myapp_db # Connect with psql neonctl connection-string --database-name myapp_db --psql ``` ## Workflow Patterns ### Feature Development Workflow ```bash # 1. Create feature branch neonctl branches create --name feature-user-auth # 2. Get connection details CONN_STRING=$(neonctl connection-string --branch-id BRANCH_ID --database-name myapp) # 3. Run migrations on feature branch psql "$CONN_STRING" -f migrations/001_add_users.sql # 4. Test changes # ... run tests ... # 5. Clean up when done neonctl branches delete feature-user-auth ``` ### Staging Environment Setup ```bash # Create staging branch neonctl branches create --name staging --compute-size medium # Create staging database neonctl databases create --branch-id STAGING_BRANCH_ID staging_db # Get connection string for deployment neonctl connection-string --branch-id STAGING_BRANCH_ID --database-name staging_db --pooled ``` ### Production Deployment ```bash # Create production-ready branch neonctl branches create --name production --compute-size large --suspend-timeout 0 # Set up production database neonctl databases create --branch-id PROD_BRANCH_ID production_db # Get production connection details neonctl connection-string --branch-id PROD_BRANCH_ID --database-name production_db --pooled ``` ## Decision Trees ### When to Create a New Branch - **New feature development** → Create feature branch - **Testing schema changes** → Create temporary test branch - **Production deployment** → Create stable production branch - **Rollback scenario** → Create branch from known good state ### Compute Size Selection - **Development/Testing** → `--compute-size small` - **Staging** → `--compute-size medium` - **Production (low traffic)** → `--compute-size large` - **Production (high traffic)** → `--compute-size xlarge` ### Connection String Types - **Development** → Direct connection - **Production** → `--pooled` for connection pooling - **Serverless apps** → `--pooled` to handle connection limits ## Advanced Operations ### Backup and Restore Simulation ```bash # Create backup branch from current state neonctl branches create --name backup-$(date +%Y%m%d) --parent-branch main # Restore by creating new branch from backup neonctl branches create --name restored-main --parent-branch backup-20231201 ``` ### Multi-Environment Management ```bash # Set up environments neonctl branches create --name development --compute-size small neonctl branches create --name staging --compute-size medium neonctl branches create --name production --compute-size large --suspend-timeout 0 # Quick environment switching export NEON_PROJECT_ID="your-project-id" export DEV_BRANCH_ID="dev-branch-id" export STAGING_BRANCH_ID="staging-branch-id" export PROD_BRANCH_ID="prod-branch-id" ``` ### Monitoring and Metrics ```bash # Get branch compute metrics neonctl branches get BRANCH_ID --show-metrics # List recent operations neonctl operations list --limit 10 # Get operation details neonctl operations get OPERATION_ID ``` ## Troubleshooting ### Authentication Issues **Error**: `Authentication required` ```bash # Solution: Re-authenticate neonctl auth # Or set API key export NEON_API_KEY="your-api-key" ``` ### Branch Creation Failures **Error**: `Branch limit exceeded` ```bash # Solution: Delete unused branches neonctl branches list neonctl branches delete UNUSED_BRANCH_ID ``` **Error**: `Invalid parent branch` ```bash # Solution: Verify parent branch exists neonctl branches list neonctl branches create --name new-branch --parent-branch VALID_BRANCH_NAME ``` ### Connection String Issues **Error**: `Database not found` ```bash # Solution: Verify database exists on branch neonctl databases list --branch-id BRANCH_ID # Create if missing neonctl databases create --branch-id BRANCH_ID DATABASE_NAME ``` ### Compute Timeout Issues **Error**: `Compute endpoint suspended` ```bash # Solution: Adjust suspend timeout neonctl branches update BRANCH_ID --suspend-timeout 7200 # Or disable auto-suspend for production neonctl branches update BRANCH_ID --suspend-timeout 0 ``` ### Project Access Issues **Error**: `Project not found` ```bash # Solution: Verify project ID and permissions neonctl projects list neonctl set-context --project-id CORRECT_PROJECT_ID ``` ## Best Practices 1. **Use descriptive branch names**: `feature-auth`, `hotfix-login`, `staging-v2` 2. **Set appropriate compute sizes** based on workload 3. **Use pooled connections** in production 4. **Clean up unused branches** regularly to stay within limits 5. **Set suspend timeouts** appropriately (0 for production, shorter for dev) 6. **Version control your database schemas** alongside branch creation 7. **Use environment variables** for connection strings in applications