【設定・環境構築】Neon → Prisma Postgres 移行とローカル開発環境の構築
設定・環境構築約5分で読めます
この記事でわかること
- Workers で TCP が使えないため Neon から HTTP 接続の Prisma Postgres に移った理由
- accelerateUrl だけで接続でき、$extends(withAccelerate()) は不要だということ
- マイグレーション用に DIRECT_URL が別途必要な理由
- HTTP 接続プール経由だと interactive transaction が不安定になる件
Prisma v7 以上、Prisma Postgres のアカウント、ローカルに PostgreSQL が稼働していること。
メモ
Neon から Prisma Postgres への DB 移行と、ローカル PostgreSQL との両立設定を解説します。
accelerateUrl コンストラクタオプション、.env の使い分け、$extends の罠など実践的なポイントをまとめました。はじめに
Cloudflare Workers では TCP ソケットが使えません。Neon のサーバーレス PostgreSQL は TCP 接続が前提のため、Workers 環境では直接接続できません。
HTTP 経由で DB に接続できる Prisma Postgres（旧 Prisma Accelerate）に移行することで、この問題を解決しました。
1. なぜ Neon から移行するのか
| Neon | Prisma Postgres | |
|---|---|---|
| 接続方式 | TCP | HTTP |
| Workers対応 | × | ○ |
| コネクションプール | Neon独自 | Prismaビルトイン |
Cloudflare Workers では TCP が使えないため、HTTP 経由の Prisma Postgres が最適です。
2. Prisma Postgres のセットアップ
Prisma Console でプロジェクトを作成すると、以下の 2 つの URL が発行されます。
# 接続用（HTTP 経由）
DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=..."
# マイグレーション用（TCP 直接）
DIRECT_URL="postgres://[email protected]:5432/postgres?sslmode=require"prisma/schema.prisma に directUrl を追加します。
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
directUrl = env("DIRECT_URL")
}3. accelerateUrl コンストラクタオプション
Prisma v7 では accelerateUrl をコンストラクタに渡すだけで Prisma Postgres 接続が有効になります。
// Workers 環境
const prisma = new PrismaClient({
accelerateUrl: process.env.DATABASE_URL,
});Tips
公式ドキュメントにある
$extends(withAccelerate()) は 不要 です。accelerateUrl コンストラクタオプションだけで動作します。$extends を使うと TypeScript の include リレーション型が壊れる罠があるので注意。4. .env でローカル/リモートを切り替え
# ローカル開発用
DATABASE_URL="postgresql://postgres:postgres@localhost:5434/anoni"
DIRECT_URL="postgresql://postgres:postgres@localhost:5434/anoni"
# 本番/ステージング用（コメントアウト）
# DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=..."
# DIRECT_URL="postgres://[email protected]:5432/postgres?sslmode=require"ローカルではコメントを切り替えるだけで、リモート DB にも接続できます。
注意
この切り替えは手軽ですが、コメントアウトを外し忘れたままテストデータを流し込む事故が起きやすいやり方でもあります。チームや長期運用なら、
.env.local / .env.production のようにファイルを分ける方が安全です。なお、本番の URL には API キーが含まれるので、.env をコミットしないこと。5. $transaction の制限
Prisma Postgres の HTTP 接続プール経由では、interactive transaction が不安定になることがあります。
// OK: 単純なトランザクション
await prisma.$transaction([
prisma.user.update({ ... }),
prisma.account.create({ ... }),
]);
// 注意: interactive transaction は不安定
await prisma.$transaction(async (tx) => {
// HTTP 接続プール経由ではタイムアウトのリスクがある
});Tips
Tips
マイグレーションは
DIRECT_URL（TCP）経由で実行されます。prisma migrate dev や prisma db push はローカルでもリモートでも同じコマンドで OK。Tips
ローカル DB リセット後は pgvector 拡張の再作成を忘れずに。
CREATE EXTENSION IF NOT EXISTS vector; をスキーマ反映前に実行しましょう。参考リンク
- Prisma Postgres ドキュメント
- Prisma: directUrl
- Prisma v7 の engineType="client" でローカル/Workers 環境を両立させる（別記事）
- Bun + Prisma 7 環境構築ガイド（別記事）
まとめ
- Workers の TCP 制約から Neon → Prisma Postgres（HTTP）に移行
accelerateUrlコンストラクタオプションでシンプルに接続（$extends不要）.envのコメント切り替えでローカル/リモートを簡単に切り替え- interactive transaction は HTTP 経由で不安定なので過度な依存は避ける
更新履歴
- .env のコメント切り替えでローカル/本番を切り替える運用のリスク（戻し忘れで本番にテストデータを流す）と、ファイルを分ける代替案を追記。壊れていた prisma.io のリンクを削除。コードブロックの言語指定を javascript から prisma に修正し、ファイルパスのキャプションを追加。見出しのエスケープをインラインコードに修正。callout の色指定を他記事と揃えた。参考リンクの節を新設。「この記事でわかること」「対象読者」「前提条件」を概要プロパティへ移動。
