Neon Postgres

Neon サーバーレス Postgres、ブランチング、コネクションプーリング、Prisma/Drizzle 統合のエキスパートパターン

パターン

Neon を使用した Prisma の接続

コネクションプーリングを使用して Prisma を Neon 用に設定します。

2つの接続文字列を使用します:

• DATABASE_URL: Prisma Client 用のプーリングされた接続
• DIRECT_URL: Prisma Migrate 用の直接接続

プーリングされた接続は PgBouncer を使用して最大 10K 接続に対応します。 マイグレーション（DDL 操作）には直接接続が必要です。

Code_example

# .env
# Pooled connection for application queries
DATABASE_URL="postgres://user:password@ep-xxx-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require"
# Direct connection for migrations
DIRECT_URL="postgres://user:password@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require"

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

// lib/prisma.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma = globalForPrisma.prisma ?? new PrismaClient({
  log: process.env.NODE_ENV === 'development'
    ? ['query', 'error', 'warn']
    : ['error'],
});

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma;
}

// Run migrations
// Uses DIRECT_URL automatically
npx prisma migrate dev
npx prisma migrate deploy

Anti_patterns

• パターン: マイグレーションにプーリングされた接続を使用 | 理由: DDL 操作が PgBouncer を通して失敗する | 修正: schema.prisma で directUrl を設定する
• パターン: コネクションプーリングを使用しない | 理由: サーバーレス関数が接続制限を超える | 修正: DATABASE_URL で -pooler エンドポイントを使用する

References

• https://neon.com/docs/guides/prisma
• https://www.prisma.io/docs/orm/overview/databases/neon

Neon サーバーレスドライバーを使用した Drizzle

エッジ/サーバーレス環境向けに、Neon のサーバーレス HTTP ドライバーで Drizzle ORM を使用します。

2つのドライバーオプション:

• neon-http: HTTP 経由の単一クエリ（単発クエリに最速）
• neon-serverless: トランザクションとセッション用 WebSocket

Code_example

# Install dependencies
npm install drizzle-orm @neondatabase/serverless
npm install -D drizzle-kit

// lib/db/schema.ts
import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: text('email').notNull().unique(),
  name: text('name'),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

// lib/db/index.ts (for serverless - HTTP driver)
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import * as schema from './schema';

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql, { schema });

// Usage in API route
import { db } from '@/lib/db';
import { users } from '@/lib/db/schema';

export async function GET() {
  const allUsers = await db.select().from(users);
  return Response.json(allUsers);
}

// lib/db/index.ts (for WebSocket - transactions)
import { Pool } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-serverless';
import * as schema from './schema';

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

// With transactions
await db.transaction(async (tx) => {
  await tx.insert(users).values({ email: 'test@example.com' });
  await tx.update(users).set({ name: 'Updated' });
});

// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './lib/db/schema.ts',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

// Run migrations
npx drizzle-kit generate
npx drizzle-kit migrate

Anti_patterns

• パターン: サーバーレスで pg ドライバーを使用 | 理由: TCP 接続がすべてのエッジ環境では機能しない | 修正: @neondatabase/serverless ドライバーを使用する
• パターン: トランザクションに HTTP ドライバーを使用 | 理由: HTTP ドライバーはトランザクションをサポートしない | 修正: トランザクション用に WebSocket ドライバー（Pool）を使用する

References

• https://neon.com/docs/guides/drizzle
• https://orm.drizzle.team/docs/connect-neon

PgBouncer によるコネクションプーリング

Neon は PgBouncer を介したビルトインコネクションプーリングを提供します。

主な制限:

• プーラーへの最大 10,000 の同時接続
• 接続はまだ基盤となる Postgres 接続を消費する
• Neon スーパーユーザー用に 7 接続が予約される

アプリケーションにはプーリングされたエンドポイント、マイグレーションには直接接続を使用します。

Code_example

# Connection string formats

# Pooled connection (for application)
# Note: -pooler in hostname
postgres://user:pass@ep-cool-name-pooler.us-east-2.aws.neon.tech/neondb

# Direct connection (for migrations)
# Note: No -pooler
postgres://user:pass@ep-cool-name.us-east-2.aws.neon.tech/neondb

// Prisma with pooling
// prisma/schema.prisma
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")      // Pooled
  directUrl = env("DIRECT_URL")        // Direct
}

// Connection pool settings for high-traffic
// lib/prisma.ts
import { PrismaClient } from '@prisma/client';

export const prisma = new PrismaClient({
  datasources: {
    db: {
      url: process.env.DATABASE_URL,
    },
  },
  // Connection pool settings
  // Adjust based on compute size
});

// For Drizzle with connection pool
import { Pool } from '@neondatabase/serverless';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,  // Max connections in local pool
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 10000,
});

// Compute size connection limits
// 0.25 CU: 112 connections (105 available after reserved)
// 0.5 CU: 225 connections
// 1 CU: 450 connections
// 2 CU: 901 connections
// 4 CU: 1802 connections
// 8 CU: 3604 connections

Anti_patterns

• パターン: リクエストごとに新しい接続を開く | 理由: 接続制限をすぐに超える | 修正: コネクションプーリングを使用し、接続を再利用する
• パターン: サーバーレスで高い max pool サイズ | 理由: 多くの関数インスタンス = 多くのプール = 多くの接続 | 修正: ローカルプールサイズを低く保つ（5-10）、PgBouncer に依存する

References

• https://neon.com/docs/connect/connection-pooling

開発用のデータベースブランチング

開発、テスト、プレビュー環境用にデータベースの即座のコピーを作成します。

ブランチは基盤となるストレージを共有（コピーオンライト）するため、 即座かつコスト効率的です。

Code_example

# Create branch via Neon CLI
neon branches create --name feature/new-feature --parent main

# Create branch from specific point in time
neon branches create --name debug/yesterday \
  --parent main \
  --timestamp "2024-01-15T10:00:00Z"

# List branches
neon branches list

# Get connection string for branch
neon connection-string feature/new-feature

# Delete branch when done
neon branches delete feature/new-feature

// In CI/CD (GitHub Actions)
// .github/workflows/preview.yml
name: Preview Environment
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  create-branch:
    runs-on: ubuntu-latest
    steps:
      - uses: neondatabase/create-branch-action@v5
        id: create-branch
        with:
          project_id: ${{ secrets.NEON_PROJECT_ID }}
          branch_name: preview/pr-${{ github.event.pull_request.number }}
          api_key: ${{ secrets.NEON_API_KEY }}
          username: ${{ secrets.NEON_ROLE_NAME }}

      - name: Run migrations
        env:
          DATABASE_URL: ${{ steps.create-branch.outputs.db_url_with_pooler }}
        run: npx prisma migrate deploy

      - name: Deploy to Vercel
        env:
          DATABASE_URL: ${{ steps.create-branch.outputs.db_url_with_pooler }}
        run: vercel deploy --prebuilt

// Cleanup on PR close
on:
  pull_request:
    types: [closed]

jobs:
  delete-branch:
    runs-on: ubuntu-latest
    steps:
      - uses: neondatabase/delete-branch-action@v3
        with:
          project_id: ${{ secrets.NEON_PROJECT_ID }}
          branch: preview/pr-${{ github.event.pull_request.number }}
          api_key: ${{ secrets.NEON_API_KEY }}

Anti_patterns

• パターン: 開発にプロダクションデータベースを共有 | 理由: データ破損、分離なしのリスク | 修正: プロダクションからの開発ブランチを作成する
• パターン: 古いブランチをクリーンアップしない | 理由: ストレージとクラッターが蓄積される | 修正: PR クローズ時にブランチを自動削除する

References

• https://neon.com/blog/branching-with-preview-environments
• https://github.com/neondatabase/create-branch-action

Vercel プレビュー環境統合

Vercel プレビューデプロイ用にデータベースブランチを自動的に作成します。各 PR は独立したデータベースを取得します。

2つの統合オプション:

• Vercel 管理: Vercel での課金、自動セットアップ
• Neon 管理: Neon での課金、より多くの制御

Code_example

# Vercel-Managed Integration
# 1. Go to Vercel Dashboard > Storage > Create Database
# 2. Select Neon Postgres
# 3. Enable "Create a branch for each preview deployment"
# 4. Environment variables automatically injected

# Neon-Managed Integration
# 1. Install from Neon Dashboard > Integrations > Vercel
# 2. Select Vercel project to connect
# 3. Enable "Create a branch for each preview deployment"
# 4. Optionally enable auto-delete on branch delete

// vercel.json - Add migration to build
{
  "buildCommand": "prisma migrate deploy && next build",
  "framework": "nextjs"
}

// Or in package.json
{
  "scripts": {
    "vercel-build": "prisma generate && prisma migrate deploy && next build"
  }
}

// Environment variables injected by integration
// DATABASE_URL - Pooled connection for preview branch
// DATABASE_URL_UNPOOLED - Direct connection for migrations
// PGHOST, PGUSER, PGDATABASE, PGPASSWORD - Individual vars

// Prisma schema for Vercel integration
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DATABASE_URL_UNPOOLED")  // Vercel variable
}

// For Drizzle in Next.js on Vercel
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';

// Use pooled URL for queries
const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql);

Anti_patterns

• パターン: すべてのプレビューで同じデータベース | 理由: プレビューが互いに干渉する | 修正: 統合でプレビューごとのブランチを有効にする
• パターン: プレビューでマイグレーションを実行しない | 理由: コードとデータベース間のスキーマ不一致 | 修正: ビルドステップに migrate コマンドを追加する

References

• https://neon.com/docs/guides/vercel-managed-integration
• https://neon.com/docs/guides/neon-managed-vercel-integration

オートスケーリングとコールドスタート管理

Neon はコンピュートリソースをオートスケールし、ゼロにスケールします。

コールドスタートレイテンシ: アイドルから復帰時に 500ms～数秒。 プロダクション推奨: スケールツーゼロを無効化し、最小コンピュートを設定する。

Code_example

# Neon Console settings for production
# Project Settings > Compute > Default compute size
# - Set minimum to 0.5 CU or higher
# - Disable "Suspend compute after inactivity"

// Handle cold starts in application
// lib/db-with-retry.ts
import { prisma } from './prisma';

const MAX_RETRIES = 3;
const RETRY_DELAY = 1000;

export async function queryWithRetry<T>(
  query: () => Promise<T>
): Promise<T> {
  let lastError: Error | undefined;

  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
    try {
      return await query();
    } catch (error) {
      lastError = error as Error;

      // Retry on connection errors (cold start)
      if (error.code === 'P1001' || error.code === 'P1002') {
        console.log(`Retry attempt ${attempt}/${MAX_RETRIES}`);
        await new Promise(r => setTimeout(r, RETRY_DELAY * attempt));
        continue;
      }

      throw error;
    }
  }

  throw lastError;
}

// Usage
const users = await queryWithRetry(() =>
  prisma.user.findMany()
);

// Reduce cold start latency with SSL direct negotiation
# PostgreSQL 17+ connection string
postgres://user:pass@ep-xxx-pooler.aws.neon.tech/db?sslmode=require&sslnegotiation=direct

// Keep-alive for long-running apps
// lib/db-keepalive.ts
import { prisma } from './prisma';

// Ping database every 4 minutes to prevent suspend
const KEEPALIVE_INTERVAL = 4 * 60 * 1000;

if (process.env.NEON_KEEPALIVE === 'true') {
  setInterval(async () => {
    try {
      await prisma.$queryRaw`SELECT 1`;
    } catch (error) {
      console.error('Keepalive failed:', error);
    }
  }, KEEPALIVE_INTERVAL);
}

// Compute sizing recommendations
// Development: 0.25 CU, scale-to-zero enabled
// Staging: 0.5 CU, scale-to-zero enabled
// Production: 1+ CU, scale-to-zero DISABLED
// High-traffic: 2-4 CU minimum, autoscaling enabled

Anti_patterns

• パターン: プロダクションでスケールツーゼロ | 理由: コールドスタートが最初のリクエストに 500ms 以上のレイテンシを追加する | 修正: プロダクションブランチのスケールツーゼロを無効化する
• パターン: コールドスタート用のリトライロジックなし | 理由: アイドル後の最初の接続がタイムアウトする可能性がある | 修正: 指数バックオフでリトライを追加する

References

• https://neon.com/blog/scaling-serverless-postgres
• https://neon.com/docs/connect/connection-latency

注意点

スケールツーゼロ後のコールドスタートレイテンシ

重大度: 高

マイグレーションにプーリングされた接続を使用

重大度: 高

サーバーレスでのコネクションプール枯渇

重大度: 高

PgBouncer 機能の制限

重大度: 中

ブランチストレージの蓄積

重大度: 中

予約接続が利用可能なプールを削減

重大度: 低

HTTP ドライバーがトランザクションをサポートしない

重大度: 中

親ブランチの削除が子に影響

重大度: 高

ブランチ間のスキーマドリフト

重大度: 中

バリデーションチェック

クライアントコード内の直接データベース URL

重大度: エラー

直接データベース URL はクライアントに決して公開されるべきではありません

メッセージ: 直接 URL がクライアントに公開されています。サーバーサイド用のプーリングされた URL のみを使用してください。

ハードコードされたデータベース接続文字列

重大度: エラー

接続文字列は環境変数を使用すべき

メッセージ: ハードコードされた接続文字列。環境変数を使用してください。

接続文字列に SSL モードが不足

重大度: 警告

Neon は SSL 接続が必要

メッセージ: sslmode=require が不足しています。接続文字列に追加してください。

Prisma でマイグレーション用の directUrl が不足

重大度: エラー

Prisma は PgBouncer を通じたマイグレーション用に directUrl が必要

メッセージ: directUrl なしのプーリングされた URL を使用しています。マイグレーションが失敗します。

Prisma directUrl がプーラーを指している

重大度: エラー

directUrl は非プーリング接続を指すべき

メッセージ: directUrl がプーラーを指しています。マイグレーション用に非プーリングエンドポイントを使用してください。

サーバーレス関数での高いプールサイズ

重大度: 警告

高いプールサイズは多くの関数インスタンスで接続を枯渇させる

メッセージ: サーバーレス用のプールサイズが高すぎます。max: 5-10 を使用してください。

リクエストごとに新しいクライアントを作成

重大度: 警告

リクエストごとにクライアントを作成すると接続を無駄にする

メッセージ: リクエストごとにクライアントを作成しています。コネクションプールまたは neon() ドライバーを使用してください。

クリーンアップ戦略なしのブランチ作成

重大度: 警告

ブランチはクリーンアップ自動化を持つべき

メッセージ: クリーンアップなしでブランチを作成しています。PR クローズに delete-branch-action を追加してください。

プロダクションで有効化されたスケールツーゼロ

重大度: 警告

スケールツーゼロはプロダクションでレイテンシを追加する

メッセージ: プロダクションでスケールツーゼロが有効です。低レイテンシに無効化してください。

トランザクションで HTTP ドライバーを使用

重大度: エラー

neon() HTTP ドライバーはトランザクションをサポートしない

メッセージ: トランザクション付き HTTP ドライバー。@neondatabase/serverless から Pool を使用してください。

コラボレーション

委譲トリガー

• ユーザーが認証が必要 -> clerk-auth (clerkId カラムを持つ User テーブル)
• ユーザーがキャッシングが必要 -> redis-specialist (クエリキャッシング、セッションストレージ)
• ユーザーが検索が必要 -> algolia-search (Postgres 機能を超えた全文検索)
• ユーザーが分析が必要 -> segment-cdp (データベースイベント、ユーザーアクションの追跡)
• ユーザーがデプロイが必要 -> vercel-deployment (環境変数、プレビューデータベース)

使用時期

• ユーザーが言及または暗示: neon データベース
• ユーザーが言及または暗示: サーバーレス postgres
• ユーザーが言及または暗示: データベースブランチング
• ユーザーが言及または暗示: neon postgres
• ユーザーが言及または暗示: postgres サーバーレス
• ユーザーが言及または暗示: コネクションプーリング
• ユーザーが言及または暗示: プレビュー環境
• ユーザーが言及または暗示: プレビューあたりのデータベース

制限事項

• このスキルは、上記で説明された範囲と明確に一致するタスクの場合にのみ使用してください。
• 出力を環境固有のバリデーション、テスト、またはエキスパートレビューの代替として扱わないでください。
• 必要な入力、権限、安全範囲、または成功基準が不明な場合は、説明を求めて停止してください。