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.

Zero Configuration Required

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

Get squashing in 2 minutes

CI/CD Integration

GitHub Actions configuration

Best Practices

Production patterns and CI/CD

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

Safety Levels

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

Typical Results

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" }
}

# 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 }}"

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

// 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;

# 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

# 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/

# Standard optimization for staging
capysquash squash db/migrations/ \
  --safety=standard \
  --output=staging/

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

Pattern 3: Connection Pooling with Serverless

// Neon connection with pooling
import { Pool } from '@neondatabase/serverless';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

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

003_alter_users.sql

004_profiles.sql

005_add_bio.sql

...

067_final_migration.sql

After Optimization

001_schema_foundation.sql

002_user_management.sql

003_profiles_and_auth.sql

004_analytics.sql

Best Practices Summary

☑ DO

Use Neon branches for testing
Optimize before major deployments
Test cold start performance
Use pooled connections
Include SSL in connection strings
Clean up test branches regularly
Validate with branch comparison

✗ 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.

Neon Integration

Branch Safe

Fast Cold Starts

Serverless Native

Quick Start

CI/CD Integration

Best Practices

Before

After

Connection Timeout

Branch Quota Exceeded

SSL Connection Required

Cold Start Still Slow

☑ DO

✗ DON'T

Supabase Integration

Drizzle ORM

CI/CD Guide

Engine API

On this page