Optimized Neon Database Context

Real-time Neon database statusline showing project name, branch, compute state, and autoscaling CU range via the Neon REST API.

When to Use This Setting

Apply this setting when you need to:

• Monitor your Neon database branch and compute state without leaving your Claude Code session
• Prevent accidental migration execution on the wrong database branch by always seeing the active branch
• Track autoscaling compute unit allocation to understand current database resource consumption Consider alternatives when:
• You do not use Neon as your database provider and the API calls would always fail
• Your Neon project has a single branch with no branching workflow to track

Quick Start

Configuration

Copy
name: optimized-neon-database-context
type: setting
category: statusline

Example Application

Copy
claude setting:apply optimized-neon-database-context

Example Output

Setting applied. Changes:
- statusLine.type: command
- statusLine.command: bash neon-api-status inline
- api_source: console.neon.tech/api/v2
- env_vars: NEON_API_KEY, NEON_PROJECT_ID
- state_icons: green(active), yellow(idle), red(suspended)

Core Concepts

Neon Context Overview

Aspect	Details
Project Info	Fetches project name from the Neon REST API using your project ID
Branch Display	Shows the default branch name, typically main, from the branches endpoint
Compute State	Displays active, idle, or suspended with color-coded icons for quick assessment
Autoscaling Range	Shows min and max CU (Compute Unit) allocation for the active endpoint
Configuration	Reads NEON_API_KEY and NEON_PROJECT_ID from environment variables or .env file

Neon API Query Architecture

+-------------------+     +-----------------------+     +------------------+
| Credential Loader |---->| Project API Call      |---->| Branch API Call  |
| .env or env vars  |     | /projects/{id}        |     | /branches        |
| API_KEY, PROJ_ID  |     | -> project name       |     | -> default branch|
+-------------------+     +-----------------------+     +------------------+
                                    |                          |
                                    v                          v
                          +---------------------+     +------------------+
                          | Endpoint API Call   |     | State Mapper     |
                          | /endpoints          |---->| active=green     |
                          | -> state, CU range  |     | idle=yellow      |
                          +---------------------+     | suspended=red    |
                                                      +------------------+

Configuration

Parameter	Type	Default	Description
neon_api_key	string	""	Bearer token for Neon REST API authentication from console.neon.tech
neon_project_id	string	""	Neon project identifier found on your Neon dashboard
api_timeout	integer	3	Maximum seconds to wait for each Neon API response
env_file_path	string	".env"	Relative path to the environment file containing Neon credentials
show_cu_range	boolean	true	Display the min-max autoscaling compute unit allocation

Best Practices

1. Store credentials in project .env files - Place NEON_API_KEY and NEON_PROJECT_ID in each project's .env file rather than global environment variables. This ensures the statusline automatically shows the correct Neon project when you switch between repositories.
2. Monitor compute state before migrations - Always verify the compute state shows active (green) before running database migrations. If the endpoint is suspended (red), the migration will trigger a cold start that may cause timeout errors for complex schema changes.
3. Use short API timeouts - The default 3-second timeout prevents the statusline from hanging when the Neon API is slow. If you experience frequent timeout-related blank displays, increase to 5 seconds, but avoid going higher as it will delay your entire statusline refresh cycle.
4. Add .env to gitignore - Your Neon API key is a sensitive credential. Ensure .env is listed in your .gitignore file to prevent accidentally committing your database access token to version control.
5. Check CU range for cost awareness - The autoscaling CU display helps you catch unexpected scaling. If your max CU is higher than expected, review your Neon project settings to avoid surprise billing from autoscaling beyond your budget.

Common Issues

1. Statusline shows config-needed - Either NEON_API_KEY or NEON_PROJECT_ID is missing. Create a .env file in your project root with both variables or export them in your shell profile and restart Claude Code.
2. Project name shows unknown - The API key may be invalid or expired. Generate a new API key from console.neon.tech and update your .env file or environment variable with the fresh token.
3. Compute state shows unknown with question mark - The endpoint query returned no results for the default branch. Verify your Neon project has at least one active endpoint by checking the Neon dashboard, and ensure the project ID matches your intended project.