Communitygithub.com

Neon サーバーレス PostgreSQL パターン

Neon を使用したエッジ/サーバーレス環境での PostgreSQL アクセス、ブランチング、スケールゼロ、接続プーリングのパターン集

Neon サーバーレス PostgreSQL パターン とは?

このスキルは、サーバーレス PostgreSQL サービスであるNeonを、エッジ/サーバーレス環境で効果的に活用するための包括的なパターン集を提供します。データベースへの HTTP クエリ (`neon()` 関数) と WebSocket 接続 (`Pool`/`Client`) の適切な使い分け、PgBouncer による接続プーリング (最大 10,000 同時接続)、そしてコピーオンライト方式による瞬時のデータベースブランチング (開発、プレビュー、CI環境向け) をカバーします。また、5分間の非アクティブで発生するコールドスタート (200~500ms) への対処法、SQLインジェクションを防ぐタグ付きテンプレートリテラルの安全な使用法、`neonctl` CLI や Neon API によるプログラム的なブランチ管理についても詳しく説明します。これにより、開発者は従来の TCP 接続が使えないエッジランタイムでも、高性能かつ安全に PostgreSQL を操作できるようになります。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-baas-neon

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Neon サーバーレス PostgreSQL パターン は何をしますか?

クイックガイド: エッジ/サーバーレス環境でのデータベースアクセスには @neondatabase/serverless を使用します。単一クエリには neon() HTTP 関数(高速、ステートレス)を優先し、インタラクティブなトランザクションには Pool/Client を使用します。サーバーレスワークロードにはプール接続文字列(-pooler サフィックス)を使用し、マイグレーションのみ直接接続を使用します。コピーオンライトセマンティクスを使用して、開発/プレビュー環境向けにデータベースをブランチします。スケールゼロからのコールドスタート(200~500msのウェイクアップ)には常に対処してください。


<critical_requirements>

重要: このスキルを使用する前に

すべてのコードは CLAUDE.md のプロジェクト規約に従うこと(ケバブケース、名前付きエクスポート、インポート順序、import type、名前付き定数)

(エッジ/サーバーレスランタイムでの単一クエリには neon() HTTP 関数を必ず使用すること -- ワンショット操作では WebSocket より 2~3 倍高速です)

(サーバーレス環境では Pool/Client の接続を同じリクエストハンドラ内で必ず閉じること -- WebSocket 接続は単一リクエストの寿命を超えて生存できません)

(サーバーレスワークロードにはプール接続文字列(-pooler サフィックス)を必ず使用すること -- 直接接続は限られた接続スロットを枯渇させます)

(スケールゼロからのウェイクアップレイテンシ(200~500ms)には、適切な接続タイムアウトとリトライロジックで必ず対処すること)

(sql.unsafe() はテーブル名やカラム名のような信頼された既知の安全な文字列にのみ使用すること -- ユーザー入力には決して使用しないでください)

</critical_requirements>


自動検出: Neon, @neondatabase/serverless, neon(), neonConfig, neon serverless driver, neon database, neon branch, neonctl, neon connection pooling, neon scale-to-zero, neon autoscaling, neon postgres, ep-*-pooler

使用すべき場合:

  • エッジ/サーバーレス関数(エッジランタイム、サーバーレスプラットフォーム)からの Postgres クエリ
  • 異なるワークロード向けの接続文字列(プール済み vs 直接)の設定
  • 開発、プレビュー、CI 環境向けのデータベースブランチの作成
  • スケールゼロ動作とコールドスタート最適化の管理
  • サーバーレスコンテキストでのトランザクション実行(HTTP バッチまたは WebSocket)
  • Neon API または neonctl CLI によるプログラム的なブランチ管理

カバーする主要パターン:

  • neon() HTTP クエリ(SQL タグ付きテンプレートと合成可能なフラグメント)
  • 適切なライフサイクル管理を伴う Pool/Client WebSocket 接続
  • プール済み(-pooler)接続文字列と直接接続文字列、それぞれの使用場面
  • データベースブランチング(開発ブランチ、PR プレビューブランチ、スキーマのみのブランチ)
  • スケールゼロ動作、コールドスタート緩和、オートスケーリング
  • 非インタラクティブな HTTP トランザクションのための sql.transaction()
  • プログラム的なブランチ管理のための Neon API と neonctl CLI

使用すべきでない場合:

  • 従来の長時間稼働サーバー接続(標準の pg ドライバーを TCP で使用)
  • 複雑な ORM 固有のパターン(ORM 独自のスキルを使用)
  • 一般的な PostgreSQL クエリ構文(SQL/Postgres スキルを使用)

詳細リソース:

  • 意思決定フレームワークとクイックルックアップテーブルについては、reference.md を参照

ドライバーとクエリ:

  • examples/core.md -- ドライバー設定、HTTP クエリ、WebSocket 接続、トランザクション

ブランチングと運用:

  • examples/branching.md -- 開発ブランチ、PR プレビュー、neonctl CLI、Neon API、CI/CD ワークフロー

哲学

Neon は PostgreSQL のストレージとコンピュートを分離し、従来の Postgres では不可能だったサーバーレス機能(スケールゼロ、インスタントブランチング、オートスケーリング)を可能にします。@neondatabase/serverless ドライバーは TCP を HTTP と WebSocket に置き換え、TCP をサポートしないエッジランタイムから Postgres にアクセスできるようにします。

コア原則:

  1. 速度には HTTP、セッションには WebSocket -- neon() 関数は単一クエリに HTTP fetch(約 3 ラウンドトリップ)を使用します。Pool/Client はセッションやインタラクティブなトランザクションが必要な場合に WebSocket(約 8 ラウンドトリップ)を使用します。適切なトランスポートを選択してください。
  2. デフォルトでプール済み -- プール接続は PgBouncer(トランザクションモード)を経由し、最大 10,000 の同時クライアントを処理します。直接接続はコンピュートサイズ(100~4,000)によって制限され、マイグレーションやセッション状態を必要とする機能にのみ使用すべきです。
  3. ブランチは低コスト -- コピーオンライトにより、500GB のデータベースのブランチはデータが分岐するまで追加のストレージを割り当てません。開発、プレビュー、テスト、CI のために自由にブランチを使用してください。
  4. スケールゼロがデフォルト -- コンピュートは 5 分間の非アクティブ状態後にサスペンドします。コールドスタートには 200~500ms かかります。タイムアウト、リトライ、接続プーリングでこれに対応してください。
  5. SQL インジェクション対策は組み込み済み -- タグ付きテンプレート関数は自動的にパラメータ化します。v1.0 以降、neon() を通常の関数として呼び出すと型エラーになり、偶発的なインジェクションを防ぎます。

Neon サーバーレスドライバーを使用すべき場合:

  • TCP 接続を開けないエッジ/サーバーレス関数
  • データベースブランチング(PR ごとのプレビュー環境)の恩恵を受けるアプリケーション
  • スケールゼロの恩恵を受けるコスト重視のワークロード
  • 接続プーリングを必要とする高同時実行サーバーレスアプリ

使用すべきでない場合:

  • 永続接続を持つ長時間実行サーバープロセス(標準の pg を TCP で使用)
  • PgBouncer を通じてセッションレベルの機能(LISTEN/NOTIFY、SET、一時テーブル)を必要とするワークロード
  • 常時オンのコンピュートを必要とする 16 CU を超えるデータベース(16 CU を超えるとスケールゼロは利用不可)

コアパターン

パターン 1: neon() を使用した HTTP クエリ

neon() 関数は、SQL タグ付きテンプレートを使用して HTTP ベースのクエリ関数を作成します。これは単一の非インタラクティブなクエリに対する最速のパスです。

import { neon } from "@neondatabase/serverless";

const DATABASE_URL = process.env.DATABASE_URL!;
const sql = neon(DATABASE_URL);

// タグ付きテンプレート -- パラメータは自動的にパラメータ化されます(インジェクションから安全)
const userId = "abc-123";
const posts =
  await sql`SELECT id, title FROM posts WHERE author_id = ${userId}`;

良い理由: タグ付きテンプレートは値を自動的にパラメータ化し SQL インジェクションを防止、HTTP は約 3 ラウンドトリップ(WebSocket は約 8)、ステートレス(管理する接続なし)

// 悪い例: neon() を通常の関数として呼び出す(v1.0+ では型エラー)
const sql = neon(DATABASE_URL);
const result = await sql(`SELECT * FROM posts WHERE id = ${id}`); // 型エラー + SQL インジェクションリスク

悪い理由: v1.0 以降、クエリ関数を通常の関数(タグ付きテンプレートではない)として呼び出すと、ランタイムおよび型エラーになります -- これは文字列補間による SQL インジェクションを防ぐために変更されました

動的 SQL のための sql.query()

クエリ文字列が変数内にある場合(テンプレートリテラルではない)、番号付きプレースホルダーとともに .query() メソッドを使用します:

const q = "SELECT * FROM posts WHERE id = $1 AND status = $2";
const posts = await sql.query(q, [postId, "published"]);

使用すべき場合: ランタイムで構築される動的 SQL 文字列、または変数に格納されたクエリ。パラメータは引き続き $1、$2 などを介して安全にパラメータ化されます。


パターン 2: 合成可能なクエリフラグメント

テンプレートクエリは、フラグメント間で自動パラメータ番号付けによる合成をサポートします。

import { neon } from "@neondatabase/serverless";

const sql = neon(DATABASE_URL);

// 再利用可能なフラグメントからクエリを構築
const whereClause = sql`WHERE status = ${"active"} AND role = ${"admin"}`;
const orderClause = sql`ORDER BY created_at DESC`;
const PAGE_SIZE = 20;
const limitClause = sql`LIMIT ${PAGE_SIZE}`;

const users =
  await sql`SELECT id, name, email FROM users ${whereClause} ${orderClause} ${limitClause}`;

良い理由: パラメータは合成されたフラグメント間で自動的に番号が付け直され、定数名でページサイズを指定、フラグメントはクエリ間で再利用可能

sql.unsafe() を使用した動的なテーブル/カラム名

// 信頼された既知の安全な値にのみ使用すること -- ユーザー入力は禁止
const TABLE_NAME = "posts";
const results =
  await sql`SELECT * FROM ${sql.unsafe(TABLE_NAME)} WHERE id = ${postId}`;

使用すべき場合: SQL でパラメータ化できない信頼された識別子(テーブル名、カラム名)を補間する必要がある場合のみ。sql.unsafe() にはユーザー指定の値を渡さないでください。


パターン 3: sql.transaction() を使用した HTTP トランザクション

WebSocket 接続を必要とせずに、HTTP 経由で複数のクエリを原子的に実行します。

import { neon } from "@neondatabase/serverless";

const sql = neon(DATABASE_URL);

// 配列形式 -- すべてのクエリが単一の HTTP ラウンドトリップで実行されます
const [posts, totalCount] = await sql.transaction([
  sql`SELECT id, title FROM posts ORDER BY created_at DESC LIMIT 10`,
  sql`SELECT count(*) FROM posts`,
]);

// トランザクションオプション付きの関数形式
const [, transferResult] = await sql.transaction(
  (txn) => [
    txn`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`,
    txn`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`,
  ],
  { isolationLevel: "Serializable" },
);

良い理由: WebSocket オーバーヘッドなしのアトミック実行、配列形式は読み取り専用バッチに簡潔、関数形式はトランザクションオプションをサポート、分離レベルは一貫性保証を制御

// 悪い例: 関連するクエリを個別の HTTP リクエストとして実行
const posts = await sql`SELECT * FROM posts WHERE author_id = ${authorId}`;
const author = await sql`SELECT * FROM users WHERE id = ${authorId}`;
// 2 つの別々の HTTP ラウンドトリップ、アトミックではない、競合状態の可能性あり

悪い理由: 別々の HTTP 呼び出しはアトミックではなく、クエリの間にデータが変更される可能性があり、ネットワークレイテンシが 2 倍になる

トランザクションオプション

  • isolationLevel: ReadUncommitted | ReadCommitted | RepeatableRead | Serializable
  • readOnly: boolean(デフォルト false)
  • deferrable: boolean(デフォルト false、readOnly: true + Serializable の場合のみ有効)

パターン 4: Pool/Client を使用した WebSocket 接続

インタラクティブなトランザクションや node-postgres API 互換性のために Pool と Client を使用します。サーバーレス環境では、接続は単一のリクエストハンドラ内で作成および閉じられる必要があります。

import { Pool } from "@neondatabase/serverless";

export async function handleRequest(request: Request): Promise<Response> {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  try {
    // ... クエリ ...
  } finally {
    await pool.end(); // 常に同じリクエスト内で閉じる
  }
}

重要なルール: ハンドラ内で Pool を作成し、finally ブロックで pool.end() を使用して閉じます。グローバルな Pool はサーバーレス呼び出し間で WebSocket 接続をリークします。

リクエストスコープの Pool、インタラクティブなトランザクション、Node.js WebSocket 設定については、examples/core.md -- パターン 5~7 を参照してください。


パターン 5: 接続文字列の設定

Neon はプール接続(PgBouncer 経由)と直接接続の 2 つの接続文字列形式を提供します。

# プール接続(注意: エンドポイント ID に -pooler サフィックス)
# 使用すべき場面: サーバーレス関数、ウェブアプリ、高同時実行ワークロード
DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require

# 直接接続(-pooler サフィックスなし)
# 使用すべき場面: マイグレーション、pg_dump、LISTEN/NOTIFY、セッションレベルの機能
DIRECT_DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require

良い理由: プール接続はトランザクションモードの PgBouncer を介して最大 10,000 の同時クライアントを処理、直接接続は管理タスク用の完全なセッション機能を提供、別々の環境変数で区別を明確にする

PgBouncer トランザクションモードの制限

プール接続は トランザクションモード で PgBouncer を実行します。つまり、各トランザクションの後で接続はプールに戻ります。これにより以下が禁止されます:

  • SET / RESET ステートメント(代わりに ALTER ROLE ... SET を使用)
  • LISTEN / NOTIFY
  • WITH HOLD CURSOR
  • SQL レベルの PREPARE / DEALLOCATE(プロトコルレベルのプリペアドステートメントは最大 1,000 までサポート)
  • PRESERVE / DELETE ROWS を使用した一時テーブル
  • セッションレベルのアドバイザリロック

パターン 6: コールドスタートとスケールゼロへの対応

Neon コンピュートはデフォルトで 5 分間の非アクティブ後に自動サスペンドします。コールドスタートには 200~500ms かかります。適切なタイムアウトとリトライロジックでこれに対応してください。

const CONNECTION_TIMEOUT_MS = 10_000;
const sql = neon(process.env.DATABASE_URL!, {
  fetchOptions: { signal: AbortSignal.timeout(CONNECTION_TIMEOUT_MS) },
});

重要なルール: コールドスタートレイテンシに対応するために明示的なタイムアウト(10~15秒)を設定します。信頼性のために指数バックオフリトライを使用します。

完全なタイムアウト設定とリトライパターンについては、examples/core.md -- パターン 8 を参照してください。

スケールゼロの事実

  • デフォルトの自動サスペンド: 5 分間の非アクティブ
  • コールドスタートレイテンシ: 約 200~500ms(リージョンとコンピュートサイズにより異なる)
  • 最大 16 CU のコンピュートでのみ利用可能(より大きなコンピュートは常時オン)
  • 有料プランではサスペンドタイムアウトを調整可能(最大 7 日間)、または完全に無効化可能
  • アクティブなロジカルレプリケーションサブスクライバーはサスペンドを防ぎます

パターン 7: データベースブランチング

Neon ブランチはコピーオンライトセマンティクスを使用します -- 500GB のデータベースのブランチは瞬時に作成され、データが分岐するまで追加のストレージを割り当てません。

# neonctl のインストール
npm install -g neonctl

# メインから開発ブランチを作成
neonctl branches create --name dev-alice --project-id <project-id>

# 自動期限切れ付きブランチを作成(CI/プレビュー用)
neonctl branches create --name preview/pr-42 --project-id <project-id> --expires-at "2025-04-01T00:00:00Z"

# スキーマのみのブランチを作成(データはコピーされない -- 機密環境向け)
neonctl branches create --name ci-test --schema-only --project-id <project-id>

# 開発ブランチを現在の本番環境にリセット
neonctl branches reset dev-alice --parent --project-id <project-id>

# ブランチを削除
neonctl branches delete preview/pr-42 --project-id <project-id>

良い理由: 名前付きブランチは git ワークフローに対応、TTL 期限切れは CI ブランチを自動クリーンアップ、スキーマのみのブランチングは機密データを保護、リセットは開発を再作成せずに本番と同期

ブランチの使用例: PR プレビュー環境

import { neon } from "@neondatabase/serverless";

const NEON_API_KEY = process.env.NEON_API_KEY;
const PROJECT_ID = process.env.NEON_PROJECT_ID;

async function createPreviewBranch(prNumber: number, prTitle: string) {
  const branchName = `preview/pr-${prNumber}`;
  const response = await fetch(
    `https://console.neon.tech/api/v2/projects/${PROJECT_ID}/branches`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${NEON_API_KEY}`,
      },
      body: JSON.stringify({
        endpoint: { type: "read_write" },
        branch: {
          parent_id: "main-branch-id",
          name: branchName,
        },
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`ブランチの作成に失敗しました: ${response.statusText}`);
  }

  const { branch } = await response.json();
  return branch;
}

良い理由: プログラム的なブランチ作成により CI/CD 自動化が可能、親ブランチ ID が分岐ポイントを制御、エンドポイントタイプが読み取り/書き込みアクセスを決定

ブランチタイプ

ブランチタイプ使用例データ期間
開発dev-alice / dev-feature-x全データプロジェクト期間中
PR プレビューpreview/pr-42全データPR の寿命(自動期限切れ)
CI テストci-test-{run-id}スキーマのみCI 実行の寿命(自動期限切れ)
本番ホットフィックスhotfix/security-patch全データ短期間(マージ後に削除)

パターン 8: 自動スケーリングとリソース管理

Neon はコンピュートリソースをワークロードに基づいて自動的にスケーリングします。最小および最大 CU(コンピュートユニット)を設定することで、予測可能性とコスト効率のバランスを取ることができます。

# neonctl を使用したコンピュート設定
neonctl endpoints update <endpoint-id> \
  --min-cu 0.25 \
  --max-cu 4 \
  --suspend-timeout 300 \
  --project-id <project-id>

良い理由: 最小 CU はベースライン性能を保証、最大 CU はコスト上限を設定、サスペンドタイムアウトは非アクティブ時のコストを制御

自動スケーリングの事実

  • CU 範囲: 最小 0.25 CU から最大 16 CU(16 CU を超えると自動スケーリングは不可、常時オン)
  • スケールアップ/ダウンは瞬時に発生、接続の切断なし
  • スケーリングは CPU とメモリの使用率に基づく
  • サスペンドタイムアウトは 5 分から 7 日間まで設定可能、または完全に無効化可能
  • 最小 CU を高く設定するとコストは増加するが、コールドスタートは減少する

パターン 9: エラーハンドリングとリトライ

サーバーレス環境では、@neondatabase/serverless ドライバーは、予期しないデータベース切断やコールドスタート遅延に対して堅牢である必要があります。

async function queryWithRetry<T>(
  queryFn: () => Promise<T>,
  maxRetries = 3,
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await queryFn();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      const retryDelay = Math.min(100 * Math.pow(2, attempt - 1), 5000);
      console.warn(
        `クエリに失敗しました(試行 ${attempt}/${maxRetries})、${retryDelay}ms 後に再試行...`,
        error,
      );
      await new Promise((resolve) => setTimeout(resolve, retryDelay));
    }
  }
  throw new Error("到達不能コード");
}

// 使用例
const sql = neon(DATABASE_URL);
const users = await queryWithRetry(
  () => sql`SELECT * FROM users WHERE status = ${'active'}`,
);

良い理由: 指数バックオフは一時的な障害によるレート制限を回避、最大リトライ回数はスタックを防ぐ、リトライ間のクリーンな接続状態

リトライが必要なエラー:

  • Connection refused / connect ECONNREFUSED - コールドスタートの可能性
  • Connection timeout / ETIMEDOUT - スケールアップ中のレイテンシ
  • 429 Too Many Requests - レート制限
  • 5xx サーバーエラー - 一時的な問題

リトライしないエラー:

  • 400 Bad Request - クライアント側の構文エラー
  • 401 Unauthorized - 認証の問題、リトライしても解決しない
  • 402 Payment Required - 割り当て超過
  • ユーザー入力の検証エラー

パターン 10: パフォーマンス最適化

Neon サーバーレスドライバーで最高のパフォーマンスを得るための重要な戦略。

import { neon, neonConfig } from "@neondatabase/serverless";

// エッジランタイム用の WebSocket 実装を構成
neonConfig.webSocketConstructor = globalThis.WebSocket;

// 複数クエリを HTTP トランザクションにバッチ処理
const sql = neon(DATABASE_URL);

// 良い: 単一 HTTP ラウンドトリップ
const [recentPosts, statistics] = await sql.transaction([
  sql`SELECT id, title FROM posts ORDER BY created_at DESC LIMIT ${limit}`,
  sql`SELECT count(*) AS total, avg(view_count) AS avg_views FROM posts`,
]);

// 悪い: 複数のラウンドトリップ
// const recentPosts = await sql`...`;
// const statistics = await sql`...`;

主要なパフォーマンスルール:

  1. 単一クエリには HTTP (neon()) を使用 - セッション状態が必要ない限り WebSocket よりも高速
  2. 複数の読み取りクエリを 1 つの sql.transaction() にバッチ処理 - 1 ラウンドトリップ vs N ラウンドトリップ
  3. 結果は常にページネーション - 大きな結果セットはメモリと帯域幅を消費
  4. WHERE 句内の接続を避ける - 関数インデックスまたはマテリアライズドビューを使用
  5. ワークロードに応じて適切な分離レベルを選択 - ReadCommitted は Serializable よりもオーバーヘッドが少ない

パフォーマンスの指標: MySQL との比較

実際のベンチマークでは、Neon サーバーレスドライバーは、同様の読み取りクエリに対して、エッジ関数内の MySQL データベース接続よりも一貫して高速でした。TCP ではなく HTTP fetch を使用することで、同一リージョンでのレイテンシが約 50~100ms 短縮されます。


パターン 11: セキュリティパターン

Neon ドライバーは、自動パラメータ化によりデフォルトで SQL インジェクションを防止しますが、適切に使用する必要があります。

import { neon } from "@neondatabase/serverless";

const sql = neon(DATABASE_URL);

// 良い: すべてのユーザー入力がパラメータ化される
const email = req.body.email;
const user = await sql`SELECT * FROM users WHERE email = ${email}`;

// 良い: 動的ソートには CASE 式を使用(安全、ドライバー内で処理)
const sortColumn = req.query.sort === "name" ? "name" : "created_at";
const sortOrder = req.query.order === "asc" ? "ASC" : "DESC";
const users = await sql`
  SELECT id, name, email
  FROM users
  ORDER BY CASE ${sortColumn}
    WHEN 'name' THEN name
    WHEN 'created_at' THEN created_at::text
  END ${sql.unsafe(sortOrder)}
`;

// 良い: 環境変数による接続情報の安全な管理
if (!process.env.DATABASE_URL) {
  throw new Error("DATABASE_URL が設定されていません");
}
const sql = neon(process.env.DATABASE_URL);

絶対にしないこと:

  • 文字列補間を使用した動的クエリの構築(例: `SELECT * FROM ${table}`)
  • sql.unsafe() へのユーザー入力の直接受け渡し
  • 環境変数や秘密情報のログ出力
  • 認証なしでのデータベース接続文字列の公開

セキュリティチェックリスト:

  • すべてのユーザー入力にはタグ付きテンプレートまたは sql.query() を使用
  • ユーザー入力に基づく動的識別子には sql.unsafe() を使用しない
  • 接続文字列は環境変数からのみ読み取る
  • データベース接続は決してログ出力しない
  • デフォルトで HTTPS を使用(Neon はデフォルトで TLS を強制)

パターン 12: マイグレーションとスキーマ管理

プールされていない直接接続を使用してデータベースマイグレーションを実行します。

# マイグレーションコマンドで直接 DATABASE_URL を使用
DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require \
  npx prisma migrate deploy

# または、.env で別々の環境変数を使用
# .env
# DIRECT_DATABASE_URL=postgresql://...(-pooler なし)
# DATABASE_URL=postgresql://...(-pooler 付き)

重要なルール: マイグレーション、pg_dump、psql セッション、またはセッション状態を必要とする管理タスクには常に直接接続文字列を使用してください。プール接続はトランザクションモードで動作するため、これらの操作は失敗します。

マイグレーションツールの設定例については、examples/branching.md を参照してください。


Pattern 13: エッジランタイムと WebSocket の構成

一部のエッジランタイム(Cloudflare Workers、Deno)は、@neondatabase/serverless 用に WebSocket の明示的な構成を必要とします。

import { neon, neonConfig } from "@neondatabase/serverless";

// クラウドフレアワーカー用
neonConfig.webSocketConstructor = WebSocket;

// Deno 用(グローバルな WebSocket を想定)
// neonConfig.webSocketConstructor = globalThis.WebSocket;

// Node.js 用(デフォルトで ws パッケージを使用、自動検出)
// 明示的な構成は通常不要

使用すべき場合: エッジランタイムで、Pool または Client を使用していて、webSocketConstructor が自動的に検出されない場合。


パターン 14: 監視とログ記録

データベースアクセスパターンとパフォーマンスを監視するために、Neon コンソールと SQL クエリを使用します。

-- 現在の接続数の確認
SELECT count(*) AS active_connections
FROM pg_stat_activity
WHERE datname = current_database()
  AND state = 'active';

-- 長時間実行クエリの特定
SELECT pid, now() - pg_stat_activity.query_start AS duration,
       query, state
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY duration DESC
LIMIT 10;

-- クエリパフォーマンス統計の確認
SELECT queryid, query, calls,
       total_exec_time / calls AS avg_time_ms,
       rows / calls AS avg_rows
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 10;

監視のベストプラクティス:

  • Neon コンソールで接続数、CPU、メモリを監視
  • コールドスタートとスケールイベントにアラートを設定
  • pg_stat_statements でパフォーマンスのボトルネックを追跡
  • サーバーレスランタイム内でクエリレイテンシをログ記録
  • ブランチ使用量を監視してストレージコストを管理

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

関連スキル