Neon

Overview

The Neon template provides a complete Postgres infrastructure for Claude Code projects. It combines Neon's Instagres provisioning service with specialized AI agents, MCP integration, and monitoring tools.

This template is designed for developers who need production-ready database infrastructure without manual configuration.

Template Architecture

The template consists of 10 components organized into four layers:

1. Provisioning Layer

neon-instagres Skill - Auto-activating skill that provisions Postgres databases via the npx get-db CLI. Triggers on keywords like "database", "postgres", or "PostgreSQL".

npx get-db --yes --ref 4eCjZDz

Creates three environment variables:

  • DATABASE_URL - Connection pooler endpoint (recommended for application queries)
  • DATABASE_URL_DIRECT - Direct connection (required for migrations and schema changes)
  • PUBLIC_INSTAGRES_CLAIM_URL - Claim URL with 72-hour validity window

using-neon Skill - Comprehensive guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development, connection methods, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Platform API/SDKs. Includes 28 reference documents.

npx claude-code-templates@latest --skill database/using-neon

Reference documentation covers:

  • Core Guides - What is Neon, getting started, features, connection methods, devtools
  • Database Drivers - Neon Serverless Driver (@neondatabase/serverless), Drizzle ORM integration
  • Auth & Data API - Neon Auth (@neondatabase/auth), Neon JS (@neondatabase/neon-js)
  • Platform API & CLI - TypeScript/Python SDKs, REST API, Neon CLI reference

2. Agent Layer

Five specialized agents handle different database operations:

neon-database-architect - Schema design with Drizzle ORM. Handles table relationships, indexes, constraints, and migration generation.

neon-auth-specialist - Authentication integration with Stack Auth. Implements multi-tenancy patterns, row-level security, and session management.

neon-migration-specialist - Production migration strategies including zero-downtime deployments, rollback procedures, and data migration patterns.

neon-optimization-analyzer - Query performance analysis using EXPLAIN ANALYZE, index recommendations, and connection pooling optimization.

neon-expert - General database consulting. Covers branching workflows, compute autoscaling, and Neon-specific features.

3. Integration Layer

neon MCP - Model Context Protocol integration providing programmatic access to Neon's management API for project and branch operations.

4. Monitoring Layer

neon-database-dev - Development metrics statusline showing active connections, transaction counts, and cache hit rates.

neon-database-resources - Resource monitoring statusline tracking CPU usage, memory consumption, and storage metrics.

Installation

Option 1: Skills Only

Install both Neon skills (provisioning + best practices):

npx claude-code-templates@latest --skill database/neon-instagres,database/using-neon

Option 2: Complete Template

Install all 10 components:

npx claude-code-templates@latest \
  --skill database/neon-instagres,database/using-neon \
  --agent database/neon-expert,database/neon-database-architect,database/neon-auth-specialist,data-ai/neon-migration-specialist,data-ai/neon-optimization-analyzer \
  --mcp database/neon \
  --setting statusline/neon-database-dev,statusline/neon-database-resources \
  --yes

Usage Patterns

Basic Database Setup

The skill auto-activates when you mention database setup:

User: "Set up a Postgres database for this project"

Skill: Provisions database, writes credentials to .env

Schema Design

Complex schemas trigger delegation to the architect agent:

User: "Create a multi-tenant SaaS schema with users, organizations, and subscriptions"

Flow: Skill provisions → delegates to neon-database-architect → generates Drizzle schema

Authentication Integration

User: "Add Stack Auth with row-level security"

Flow: Delegates to neon-auth-specialist → implements RLS policies and auth tables

Production Migration

User: "Migrate to production with zero downtime"

Flow: Delegates to neon-migration-specialist → creates migration strategy with rollback plan

Framework Integration

The template integrates with major JavaScript/TypeScript frameworks:

  • Next.js - Writes to .env.local, configures for server components and API routes
  • Vite - Creates .env with VITE_ prefix for client-side access
  • Express - Standard .env configuration with connection pooling setup
  • SvelteKit - Writes to .env with $env/static/private patterns
  • Remix - Creates .env for server-side loaders and actions

ORM support includes Drizzle, Prisma, TypeORM, Kysely, and raw SQL via node-postgres.

Technical Implementation

Database Provisioning

Neon Instagres creates serverless Postgres instances with the following characteristics:

  • Postgres 16 with standard extensions (pgvector, PostGIS, uuid-ossp, etc.)
  • Connection pooling via PgBouncer in transaction mode
  • Autoscaling compute from 0.25 to 8 vCPU based on load
  • 72-hour trial period before requiring account claim

Agent Delegation Logic

The skill uses keyword matching to delegate to appropriate agents:

  • schema, table, drizzle → neon-database-architect
  • auth, stack auth, RLS → neon-auth-specialist
  • migrate, migration, production → neon-migration-specialist
  • slow, optimize, performance → neon-optimization-analyzer
  • branch, scale → neon-expert

MCP Integration

The Neon MCP exposes management operations:

  • List and create projects
  • Manage database branches (create, delete, merge)
  • Configure compute settings and autoscaling
  • Query connection strings and endpoints

Additional Resources

Back to Components