neon-vercel-postgres

Neon と Vercel Serverless Postgres

ステータス：本番環境で利用可能 最終更新日：2025-11-21 依存関係：なし 最新バージョン：@neondatabase/[email protected]、@vercel/[email protected]、[email protected]、[email protected]

---

クイックスタート（5 分）

1. プラットフォームを選択する

オプション A：Neon Direct（マルチクラウド、Cloudflare Workers、あらゆるサーバーレス環境）

bun add @neondatabase/serverless

オプション B：Vercel Postgres（Vercel 専用、Vercel で設定不要）

bun add @vercel/postgres

重要な理由：

• Neon direct では、マルチクラウドの柔軟性とブランチ API を利用できます
• Vercel Postgres では、Vercel で設定不要で、自動的に環境変数が設定されます
• どちらも HTTP ベース（TCP なし）なので、サーバーレス／エッジ環境に最適です

2. 接続文字列を取得する

Neon Direct の場合：

# Sign up at https://neon.tech
# Create a project → Get connection string
# Format: postgresql://user:[email protected]/dbname?sslmode=require

Vercel Postgres の場合：

# In your Vercel project
vercel postgres create
vercel env pull .env.local  # Automatically creates POSTGRES_URL and other vars

重要：

• サーバーレスではプール済み接続文字列（-pooler.region.aws.neon.tech で終わるもの）を使用してください
• プールされていない接続は、サーバーレス環境ではすぐに枯渇します
• 必ず ?sslmode=require パラメーターを含めてください

3. データベースにクエリを実行する

Neon Direct：

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

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

// Simple query
const users = await sql`SELECT * FROM users WHERE id = ${userId}`;

// Transactions
const result = await sql.transaction([
  sql`INSERT INTO users (name) VALUES (${name})`,
  sql`SELECT * FROM users WHERE name = ${name}`
]);

Vercel Postgres：

import { sql } from '@vercel/postgres';

// Simple query
const { rows } = await sql`SELECT * FROM users WHERE id = ${userId}`;

// Transactions
const client = await sql.connect();
try {
  await client.sql`BEGIN`;
  await client.sql`INSERT INTO users (name) VALUES (${name})`;
  await client.sql`COMMIT`;
} finally {
  client.release();
}

重要：

• SQL インジェクションを自動的に防ぐため、テンプレートタグ構文（sql`...`）を使用してください
• 文字列を連結しないでください：sql('SELECT * FROM users WHERE id = ' + id) ❌

---

重要なルール

必ず行うこと

✅ サーバーレス環境ではプール済み接続文字列（ホスト名に -pooler. を含むもの）を使用する

✅ SQL インジェクションを防ぐため、クエリにはテンプレートタグ構文（sql`SELECT * FROM users`）を使用する

✅ 接続文字列に sslmode=require を含める

✅ トランザクション後に接続を解放する（Vercel Postgres の手動トランザクション）

✅ エッジ互換の TypeScript ORM には Drizzle ORM を使用する（Cloudflare Workers では Prisma を使用しない）

✅ 接続文字列は環境変数として設定する（ハードコードしない）

✅ プレビュー環境とテストには Neon のブランチ機能を使用する

✅ Neon のダッシュボードで接続プールの使用状況を監視する

✅ try/catch ブロックでエラーを処理し、失敗時にはトランザクションをロールバックする

✅ 作成／更新したデータを 1 回のクエリで取得するため、INSERT／UPDATE には RETURNING 句を使用する

絶対に行わないこと

❌ サーバーレス関数でプールされていない接続を使用しない（接続プールが枯渇します）

❌ SQL 文字列を連結しない（'SELECT * FROM users WHERE id = ' + id）- SQL インジェクションのリスクがあります

❌ sslmode=require を省略しない - 接続に失敗するか、安全でない接続になります

❌ Vercel Postgres の手動トランザクションで client.release() を忘れない - 接続リークが発生します

❌ Cloudflare Workers で Prisma を使用しない - Node.js ランタイムが必要です（代わりに Drizzle を使用してください）

❌ 接続文字列をハードコードしない - 環境変数を使用してください

❌ エッジ関数からマイグレーションを実行しない - Node.js 環境または Neon コンソールを使用してください

❌ .env ファイルをコミットしない - .gitignore に追加してください

❌ サーバーレス関数で POSTGRES_URL_NON_POOLING を使用しない - プーリングの効果がなくなります

❌ 接続数の上限を超えない - 使用状況を監視し、必要に応じてプランをアップグレードしてください

---

よくあるエラー上位 5 件（残り 15 件は references/error-catalog.md を参照）

エラー #1：接続プールの枯渇

エラー：Error: connection pool exhausted または too many connections for role 解決策：プールされていない接続ではなく、プール済み接続文字列（-pooler.region.aws.neon.tech で終わるもの）を使用してください

エラー #2：TCP 接続がサポートされていない

エラー：Error: TCP connections are not supported in this environment 解決策：pg や postgres.js（TCP ベース）ではなく、@neondatabase/serverless（HTTP ベース）を使用してください

エラー #3：文字列連結による SQL インジェクション

エラー：SQL インジェクション攻撃が成功する 解決策：必ずテンプレートタグ（sql`SELECT * FROM users WHERE id = ${id}`）を使用し、文字列を連結しないでください

エラー #4：SSL モードの設定漏れ

エラー：Error: connection requires SSL 解決策：接続文字列の末尾に必ず ?sslmode=require を追加してください

エラー #5：接続リーク（Vercel Postgres）

エラー：メモリ使用量が徐々に増加する 解決策：手動トランザクションの後は、必ずfinallyブロックでclient.release()を呼び出します。

詳細な解決策とトラブルシューティングガイドについては、references/error-catalog.mdを読み込んでください。15件のエラーすべてが記載されています。

---

よくあるユースケース

ユースケース 1：Neon を使用した Cloudflare Worker

用途：Cloudflare Workers 上で Postgres を使用したサーバーレス API をデプロイする場合 クイックパターン：

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

export default {
  async fetch(request: Request, env: Env) {
    const sql = neon(env.DATABASE_URL);
    const users = await sql`SELECT * FROM users`;
    return Response.json(users);
  }
};

読み込むファイル：references/common-patterns.md → パターン 1

ユースケース 2：Next.js Server Actions

用途：Vercel Postgres を使用した Next.js アプリを構築する場合 クイックパターン：

'use server';
import { sql } from '@vercel/postgres';

export async function getUsers() {
  const { rows } = await sql`SELECT * FROM users`;
  return rows;
}

読み込むファイル：references/common-patterns.md → パターン 2

ユースケース 3：Drizzle による型安全なクエリ

用途：完全な TypeScript の型安全性とエッジ互換性が必要な場合 読み込むファイル：references/common-patterns.md → パターン 3

ユースケース 4：データベーストランザクション

用途：複数の操作がすべて成功するか、すべて失敗する必要がある場合（例：送金） 読み込むファイル：references/common-patterns.md → パターン 4

ユースケース 5：ブランチ機能を使ったプレビュー環境

用途：プルリクエストまたはプレビューのデプロイごとに、分離されたデータベースが必要な場合 読み込むファイル：references/common-patterns.md → パターン 5

---

リファレンスを読み込むタイミング

次の場合はreferences/setup-guide.mdを読み込んでください：

• ユーザーが完全な7ステップのセットアップ手順を必要としている
• ユーザーが Drizzle ORM または Prisma との統合について質問している
• ユーザーが環境変数や接続文字列についてサポートを必要としている
• ユーザーが Cloudflare Workers または Vercel へのデプロイについて質問している

次の場合はreferences/error-catalog.mdを読み込んでください：

• 接続、クエリ、デプロイに関するエラーが発生している
• ユーザーから「接続プールが枯渇した」またはタイムアウトのエラーが報告された
• ユーザーが SQL インジェクションの防止について質問している
• Prisma または Drizzle の問題に関するトラブルシューティングが必要である

次の場合はreferences/common-patterns.mdを読み込んでください：

• ユーザーがコード例やテンプレートを求めている
• ユーザーがトランザクション、ページネーション、検索を実装する必要がある
• ユーザーが Server Actions、Cloudflare Workers、Drizzle のパターンについて質問している
• ユーザーが本番環境で検証済みのパターンを確認したい

次の場合はreferences/advanced-topics.mdを読み込んでください：

• ユーザーが Neon のブランチ機能やデータベースのワークフローについて質問している
• 接続プーリングの詳細な解説が必要である
• ユーザーがパフォーマンスの最適化やクエリのチューニングについて質問している
• セキュリティのベストプラクティス（RLS、暗号化、監査ログ）が必要である
• ユーザーがバックアップや災害復旧について質問している

---

設定ファイルのリファレンス

package.json（Neon 直接利用）

{
  "dependencies": {
    "@neondatabase/serverless": "^1.0.2"
  }
}

package.json（Vercel Postgres）

{
  "dependencies": {
    "@vercel/postgres": "^0.10.0"
  }
}

package.json（Drizzle ORM を使用）

{
  "dependencies": {
    "@neondatabase/serverless": "^1.0.2",
    "drizzle-orm": "^0.44.7"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.0"
  },
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio"
  }
}

drizzle.config.ts

import { defineConfig } from 'drizzle-kit';

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

これらの設定を使う理由：

• @neondatabase/serverlessはエッジに対応しています（HTTP/WebSocket ベース）
• @vercel/postgresを使うと、Vercel 上で設定不要です
• drizzle-ormはすべてのランタイム（Cloudflare Workers、Vercel Edge、Node.js）で動作します
• drizzle-kitはマイグレーションとスキーマ生成を処理します

---

バンドルされているリソースの使用

テンプレート（templates/）

drizzle-schema.ts - users、posts、リレーションを含む完全な Drizzle スキーマ

// See templates/drizzle-schema.ts for full example

drizzle-queries.ts - 一般的なクエリパターン（SELECT、INSERT、UPDATE、DELETE、結合）

// See templates/drizzle-queries.ts for full example

drizzle-migrations-workflow.md - 完全なマイグレーションワークフローガイド

// See templates/drizzle-migrations-workflow.md for full guide

neon-basic-queries.ts - Neon を使用した生 SQL クエリのパターン

// See templates/neon-basic-queries.ts for full example

package.json - 完全な依存関係の設定

// See templates/package.json for full config

リファレンス（references/）

• setup-guide.md - 完全な7ステップのセットアップ手順（インストール → デプロイ）
• error-catalog.md - 解決策とトラブルシューティングを含む15件すべてのエラー
• common-patterns.md - 5つ以上の本番環境向けパターン（Cloudflare Workers、Next.js、Drizzle、トランザクション、ブランチ機能）
• advanced-topics.md - ブランチ機能のワークフロー、接続プーリング、パフォーマンス、セキュリティ

依存関係

必須：

• @neondatabase/serverless@^1.0.2 - Neon のサーバーレス Postgres クライアント（HTTP/WebSocket ベース）
• @vercel/postgres@^0.10.0 - Vercel Postgres クライアント（Neon への直接接続の代替、Vercel 専用）

任意：

• drizzle-orm@^0.44.7 - TypeScript ORM（エッジ環境に対応、推奨）
• drizzle-kit@^0.31.0 - Drizzle のスキーママイグレーションとイントロスペクション
• @prisma/client@^6.10.0 - Prisma ORM（Node.js 専用、エッジ環境には非対応）
• @prisma/adapter-neon@^6.10.0 - Neon のサーバーレス向け Prisma アダプター
• neonctl@^2.16.1 - データベース管理用の Neon CLI
• zod@^3.24.0 - 入力のサニタイズ用スキーマ検証

---

公式ドキュメント

• Neon ドキュメント：https://neon.tech/docs
• Neon サーバーレスパッケージ：https://github.com/neondatabase/serverless
• Vercel Postgres：https://vercel.com/docs/storage/vercel-postgres
• Vercel Storage（すべて）：https://vercel.com/docs/storage
• Neon ブランチ作成ガイド：https://neon.tech/docs/guides/branching
• Neonctl CLI：https://neon.tech/docs/reference/cli
• Drizzle + Neon：https://orm.drizzle.team/docs/quick-postgresql/neon
• Prisma + Neon：https://www.prisma.io/docs/orm/overview/databases/neon
• Context7 ライブラリ ID：/github/neondatabase/serverless、/github/vercel/storage

---

パッケージのバージョン（2025-10-29 に確認）

{
  "dependencies": {
    "@neondatabase/serverless": "^1.0.2",
    "@vercel/postgres": "^0.10.0",
    "drizzle-orm": "^0.44.7"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.0",
    "neonctl": "^2.16.1"
  }
}

最新の Prisma（必要な場合）：

{
  "dependencies": {
    "@prisma/client": "^6.10.0",
    "@prisma/adapter-neon": "^6.10.0"
  },
  "devDependencies": {
    "prisma": "^6.10.0"
  }
}

---

本番環境での例

このスキルは、Neon と Vercel Postgres の本番環境へのデプロイを基にしています。

• Cloudflare Workers：API の1日あたりのリクエスト数は50K以上、接続エラーは0件
• Vercel Next.js App：月間ユーザー数10万人の EC サイト
• ビルド時間：5分未満（初期セットアップ）、30秒未満（デプロイ）
• エラー：0件（既知の問題15件をすべて防止）
• 検証項目：✅ 接続プーリング、✅ SQL インジェクション対策、✅ トランザクション処理、✅ ブランチ作成ワークフロー

---

セットアップ完了チェックリスト

このチェックリストを使用して、セットアップを確認してください。

• パッケージをインストール済み（@neondatabase/serverless または @vercel/postgres）
• Neon データベースを作成済み（または Vercel Postgres をプロビジョニング済み）
• プール接続文字列を取得済み（末尾が -pooler.）
• 接続文字列に ?sslmode=require が含まれている
• 環境変数を設定済み（DATABASE_URL または POSTGRES_URL）
• データベーススキーマを作成済み（生の SQL、Drizzle、または Prisma）
• クエリでテンプレートタグ構文（sql`...`）を使用している
• トランザクションで適切な try/catch を使用し、接続を解放している
• 接続プーリングを確認済み（プール接続文字列を使用）
• 実行環境に適した ORM を選択済み（エッジ環境では Drizzle、Node.js では Prisma）
• 開発用データベースでローカルテスト済み
• 本番環境またはプレビュー環境にデプロイし、テスト済み
• Neon ダッシュボードで接続モニタリングを設定済み

---

ご質問や問題がありますか？

1. references/error-catalog.md で15件すべてのエラーとトラブルシューティングを確認してください
2. references/setup-guide.md で全7ステップのセットアップ手順を確認してください
3. references/common-patterns.md で本番環境で検証済みのコード例を確認してください
4. 公式ドキュメントを確認してください：https://neon.tech/docs
5. サーバーレス環境ではプール接続文字列を使用していることを確認してください
6. 接続文字列に sslmode=require が含まれていることを確認してください