neon-expert — Claude Code subagent for Neon: setup and use
Get guidance on Neon Serverless Postgres setup, connections, branching, and scaling. The subagent routes schema, auth, and query-diagnosis work to specialists.
npx claude-code-templates@latest --agent database/neon-expertWhat neon-expert does
This subagent handles general Neon questions, from project setup and CLI or Management API use to connection pooling, database branches, and autoscaling. It can suggest commands and query examples for routine tasks. Schema and ORM work goes to neon-database-architect; authentication goes to neon-auth-specialist; slow-query diagnosis goes to neon-optimization-analyzer.
It explains when to use a direct connection versus Neon’s pooler. The pooler runs in transaction mode, so session-level SET, LISTEN/NOTIFY, and SQL PREPARE/DEALLOCATE are unavailable there. Code that depends on those features needs a direct connection. In serverless handlers, create and close connections within each request.
Install it in Claude Code with npx claude-code-templates@latest --agent database/neon-expert; its agent file is .claude/agents/neon-expert.md. The subagent has Read, Bash, and Grep tools, not MCP access, so it uses the CLI for Neon operations.
What it helps with
- configure an application connection to Neon
- choose between a direct connection and the pooler
- create a database branch for testing
- understand Neon autoscaling behavior
- route schema design to a specialist subagent
Example prompts for the agent
- Set up my app's Neon connection and show a test query.
- Explain whether this project should use a direct or pooled connection.
- Show me how to create a Neon test branch and retrieve its connection string.
How to install neon-expert
1claude-code-templates
npx claude-code-templates@latest --agent database/neon-expert2Manually: put the files in place
.claude/agents/neon-expert.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/neon-expert.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/neon-expert.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about neon-expert
How do I install neon-expert in Claude Code?
Run npx claude-code-templates@latest --agent database/neon-expert. The agent file is .claude/agents/neon-expert.md.
What does neon-expert do?
It advises on Neon Serverless Postgres setup, CLI and API use, connections, branches, and scaling. It routes schema, authentication, and slow-query work to dedicated subagents.
What does Neon’s pooled connection support?
The pooler uses transaction mode, which does not support session-level SET, LISTEN/NOTIFY, or SQL PREPARE/DEALLOCATE. Use a direct connection for those operations, or the driver’s prepared-statement API.
