---

Title: Neon Integration. Description: Optimize Neon PostgreSQL migrations with intelligent auto-detection of serverless patterns, branching workflows, and edge SQL.

Neon Integration

Optimize Neon PostgreSQL migrations with intelligent auto-detection of serverless patterns, branching workflows, and edge SQL optimizations

CAPYSQUASH understands Neon's unique serverless architecture and optimizes migrations while preserving all Neon-specific functionality including branching, connection pooling, and edge SQL capabilities. No configuration required-just connect and optimize.

CAPYSQUASH automatically detects Neon projects and activates specialized optimization rules. Serverless patterns, branching workflows, connection pooling, and edge SQL are all preserved during consolidation.

Why Neon + CAPYSQUASH?

Neon's serverless PostgreSQL revolutionizes database management with branching and instant provisioning. CAPYSQUASH keeps your migrations clean while leveraging Neon's powerful features.

Branch Safe

Handles Neon's git-like branching workflows without breaking merge operations

Fast Cold Starts
Typical projects see 70-80% faster cold starts with optimized migrations
Serverless Native
Preserves connection pooling, edge SQL, and serverless scaling patterns

Quick Start

Install CAPYSQUASH

Choose your preferred method:

Sign up at capysquash.dev
Create an organization
Connect your GitHub repository

Auto-detection handles the rest

# macOS/Linux

brew install capysquash-cli

# Or use Go

go install github.com/CAPYSQUASH/capysquash-cli/cmd/capysquash@latest

npm install -g capysquash-cli

Analyze Your Migrations

capysquash analyze db/migrations/

What you'll see: ` [Plugins] ✓ Neon PostgreSQL detected [plugins] ✓ Found serverless connection patterns [plugins] ✓ Found 3 branch-specific migrations [plugins] ✓ Found edge SQL optimizations [plugins] ✓ Optimization potential: 67 → 9 files (87% reduction)

Optimize with Safety

capysquash squash db/migrations/ \
  --output=clean/ \
  --safety=standard

conservative: Production-safe (50-60% reduction)

standard: Recommended balance (70-80% reduction)

aggressive: Maximum optimization (85-95% reduction, dev only)

Create Neon Branch for Testing

# Install Neon CLI

npm install -g neonctl

# Create test branch

neonctl branches create \
  --project-id your-project-id \
  --name squash-test

# Get connection string

neonctl connection-string squash-test

Test on Neon Branch

# Apply squashed migrations

psql "postgres://user:pass@branch.neon.tech/db" \
  -f clean/001_consolidated.sql

# Validate schema

capysquash validate \
  --original db/migrations/ \
  --squashed clean/

Deploy to Production

# Replace old migrations

mv db/migrations db/migrations_backup
mv clean db/migrations

# Deploy to Neon

git add db/migrations
git commit -m "chore: optimize migrations"
git push

Before: 67 migration files, 5min cold start After: 9 migration files, 0.8sec cold start (6x faster!)

How CAPYSQUASH Detects Neon Projects

CAPYSQUASH automatically identifies Neon projects and activates specialized optimization:

Auto-Detection Triggers

Neon connection strings in configuration Serverless-specific connection patterns Branching-related migration patterns Edge SQL function definitions PgBouncer pooling configurations

[plugins] ✓ Neon PostgreSQL detected
[plugins] ✓ Found serverless connection patterns
[plugins] ✓ Found 3 branch-specific migrations
[plugins] ✓ Found edge SQL optimizations
[plugins] ✓ Found PgBouncer configuration
[plugins] ✓ Ready for Neon-optimized consolidation

You can force the Neon plugin with configuration:

{
  "database_connection": { "platform": "neon" }
}

Branching Workflows

Neon's git-like branching is powerful but creates unique migration challenges. CAPYSQUASH handles these automatically.

Branch-Based Validation Workflow

Create Test Branches

# Create branches for comparison

neonctl branches create --name original-test
neonctl branches create --name squashed-test

Apply Migrations to Both Branches

# Apply original migrations

psql "$ORIGINAL_BRANCH_URL" < db/migrations/*.sql

# Apply squashed migrations

psql "$SQUASHED_BRANCH_URL" < clean/*.sql

Compare Schemas

# Dump and compare schemas

pg_dump "$ORIGINAL_BRANCH_URL" --schema-only > original_schema.sql
pg_dump "$SQUASHED_BRANCH_URL" --schema-only > squashed_schema.sql
diff original_schema.sql squashed_schema.sql

Deploy to Production

If schemas match, promote the squashed branch:

neonctl branches promote squashed-test --to main

Example: Consolidating Branch Migrations

-- Before: Branch-specific migrations scattered

-- Branch: feature/user-auth
CREATE TABLE users (id uuid, email text);
ALTER TABLE users ADD COLUMN created_at timestamptz;

-- Branch: feature/user-profiles
CREATE TABLE profiles (id uuid, user_id uuid);
ALTER TABLE profiles ADD COLUMN bio text;

-- After: Consolidated with branch awareness
CREATE TABLE users (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  email text NOT NULL UNIQUE,
  created_at timestamptz DEFAULT now()
);

CREATE TABLE profiles (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id uuid REFERENCES users(id) ON DELETE CASCADE,
  bio text,
  created_at timestamptz DEFAULT now()
);

Connection Pooling & Serverless Patterns

CAPYSQUASH preserves PgBouncer and connection pooler configurations essential for Neon's serverless architecture.

Pooling Configuration Preservation

-- Before: Pooling config scattered across migrations
ALTER DATABASE neondb SET statement_timeout = '60s';
ALTER ROLE neondb_owner SET pool_mode = 'transaction';
ALTER ROLE neondb_owner SET default_pool_size = 25;

-- After: Optimized pooling configuration
ALTER DATABASE neondb SET
  statement_timeout = '60s',
  idle_in_transaction_session_timeout = '30s';

ALTER ROLE neondb_owner SET
  pool_mode = 'transaction',
  default_pool_size = 25,
  max_client_conn = 100;

Cold Start Optimization

Fewer migrations = faster cold starts on Neon's serverless architecture:

Before

287 migration files ~3s cold start time High connection overhead

After

12 migration files ~0.8s cold start time 73% faster startup

Edge SQL Optimization

CAPYSQUASH preserves edge-optimized functions while consolidating:

-- Before: Multiple edge function migrations
CREATE OR REPLACE FUNCTION get_user_nearest(user_id uuid)
RETURNS TABLE (edge_location text, latency_ms int) AS $$
BEGIN
  -- Edge-specific logic
END;
$$ LANGUAGE plpgsql;

ALTER FUNCTION get_user_nearest(user_id uuid) SET enable_seqscan = off;

-- After: Optimized edge function
CREATE OR REPLACE FUNCTION get_user_nearest(user_id uuid)
RETURNS TABLE (edge_location text, latency_ms int) AS $$
BEGIN
  -- Edge-specific logic with optimizations
END;
$$ LANGUAGE plpgsql SET enable_seqscan = off;

CI/CD Integration

GitHub Actions with Neon

name: Optimize and Deploy to Neon

on:
push:
branches: [main]

jobs:
optimize-deploy:
runs-on: ubuntu-latest
steps:
\- uses: actions/checkout@v4

      name: Install tools
        run: |
          go install github.com/CAPYSQUASH/capysquash-cli/cmd/capysquash@latest
          npm install -g neonctl

      name: Squash migrations
        run: |
          capysquash squash db/migrations/ \
            --safety=standard \
            --output=db/clean/

      name: Create test branch
        env:
          NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
        run: |
          neonctl branches create \
            --project-id ${{ secrets.NEON_PROJECT_ID }} \
            --name "ci-${{ github.sha }}"

      name: Test on Neon branch
        env:
          NEON_CONNECTION_STRING: ${{ secrets.NEON_CONNECTION_STRING }}
        run: |
          psql "$NEON_CONNECTION_STRING" < db/clean/*.sql

      name: Validate
        run: |
          capysquash validate db/migrations/ db/clean/

      name: Deploy to production
        if: success()
        run: |
          neonctl branches promote "ci-${{ github.sha }}"


</Tab>

<Tab value="Branch Validation">
  ```yaml
name: Validate on PR

on:

pull_request:

paths:

\- 'db/migrations/\*\*'

jobs:

validate:

runs-on: ubuntu-latest

steps:

\- uses: actions/checkout@v4

name: Install capysquash
\- run: |
\- go install github.com/CAPYSQUASH/capysquash-cli/cmd/capysquash@latest

name: Analyze migrations
\- run: |
\- capysquash analyze db/migrations/ --quiet

name: Squash (dry-run)
\- run: |
\- capysquash squash db/migrations/
\--output clean/
\--safety=conservative
\--dry-run

name: Validate
\- run: |
\- capysquash validate
\--original db/migrations/
\--squashed clean/
\--db-image postgres:15






---

## ORM Integration

### Drizzle with Neon




  ```typescript
  // drizzle.config.ts
  import type { Config } from 'drizzle-kit';

export default {
schema: './src/db/schema.ts',
out: './drizzle/migrations',
driver: 'pg',
dbCredentials: {
connectionString: process.env.DATABASE_URL!,
},
} satisfies Config;


</Tab>

<Tab value="Workflow">
  ```bash
# Generate Drizzle migrations

pnpm drizzle-kit generate:pg

# Squash generated migrations

capysquash squash drizzle/migrations/

\--safety=standard

### \ Output=drizzle/clean

# Push to Neon

pnpm drizzle-kit push:pg






### Prisma with Neon

```bash

# Generate Prisma migrations

npx prisma migrate dev --create-only

# Squash all migrations

capysquash squash prisma/migrations/ \
--output=prisma/clean/ \
--safety=standard

# Deploy to Neon

npx prisma migrate deploy

Common Patterns

Pattern 1: Feature Branch Workflow


# On feature branch with new migrations

git checkout -b feature/new-auth

# Add migrations (Drizzle/Prisma/raw SQL)

npm run db:migrate

# Before merging, optimize

capysquash squash db/migrations/ --output=clean/

# Test on Neon branch

neonctl branches create --name feature-test
psql "$(neonctl connection-string feature-test)" < clean/*.sql

# Merge if successful

git add db/migrations
git commit -m "feat: add authentication system"

Pattern 2: Multi-Environment Setup

# Aggressive optimization for dev

capysquash squash db/migrations/
\--safety=aggressive
\--output=dev/


</Tab>

<Tab value="Staging">
  ```bash
# Standard optimization for staging

capysquash squash db/migrations/

\--safety=standard

### \ Output=staging




    ```bash
    # Conservative for production

  capysquash squash db/migrations/
  \--safety=conservative
  \--output=production/

</Tab>

</Tabs>

### Pattern 3: Connection Pooling with Serverless

```typescript
// Neon connection with pooling.

Const pool = new Pool(.
connectionString: process.env.DATABASE_URL,
);

// Faster schema validation with fewer migrations.
Await pool.query('SELECT 1');

Troubleshooting

Connection Timeout

Error: connection to server ... failed: timeout

Solution:

export DATABASE_URL="postgres://...@...neon.tech/db?sslmode=require&connect_timeout=30"

{
  "validation": {
    "connection_timeout": 30
  }
}

Branch Limit Reached

Error: Branch limit reached for project.

Solution:

neonctl branches list | grep "test-" | \
  xargs -I {} neonctl branches delete {}

capysquash validate --docker db/migrations/ clean/

SSL Connection Required

Error: SSL connection required.

Solution:

export DATABASE_URL="postgres://...neon.tech/db?sslmode=require"
psql "postgres://...neon.tech/db?sslmode=require"

Cold Starts Remain Slow

Solution:

Verify migration count reduction.
Check for unused indexes.
Consider more aggressive optimization.
Review connection pooling settings.

capysquash squash db/migrations/ \
  --safety=aggressive \
  --output=optimized

✗ DON'T

Deploy without branch testing Skip SSL verification Leave test branches running Use aggressive in production Forget connection timeouts Ignore cold start metrics Skip schema validation

Performance Metrics

Metric	Before	After	Improvement
Migration Files	67-134	9-16	85-90% reduction
Cold Start Time	3-5 sec	0.8-1.5 sec	70-80% faster
Deployment Time	5-11 min	30-90 sec	8-12x faster
Branch Merges	Conflict-prone	Smooth	100% success
Connection Pooling	Often broken	Always preserved	Zero issues

Having issues with Neon optimization? Check our troubleshooting guide or join our Discord for support.

---

On this page