ClickHouse Managed Postgres で Prisma を使用する

Prisma ORM は、宣言的なスキーマ、移行ツール (Prisma Migrate)、自動生成される型安全なクライアントを備えた TypeScript 向けの ORM です。このガイドでは、Prisma を ClickHouse Managed Postgres に接続し、移行によってテーブルを作成したうえで、スクリプトと小規模な HTTP エンドポイントからそのテーブルにクエリを実行します。このガイドでは、現行の安定版リリースである Prisma ORM 7 (7.10.0 で動作確認済み) を使用します。

前提条件

Node.js 20.19、22.12、または 24 以降
ClickHouse Managed Postgres サービス
データベースを作成するための psql。CREATE DATABASE ステートメントは SQL コンソールで実行することもできます。
macOS の場合: Prisma Migrate を実行するための Docker (移行を実行するを参照)

ClickHouse Managed Postgres サービスを作成する

ClickHouse Cloud コンソールで New service をクリックし、Postgres を選択します。インスタンスは数分で利用可能になります。詳しい手順については、クイックスタートを参照してください。

接続情報を取得する

サービスの左サイドバーで Connect をクリックします。表示されるモーダルには、ユーザー名、パスワード、サーバー、ポートのほか、そのまま使える接続文字列が表示されます。 Prisma にはデータベースと通信するコンポーネントが 2 つあるため、このガイドでは 2 種類の接続を使用します。

アプリケーション (Prisma Client) は、ポート 6432 で PgBouncer 経由 で接続します。PgBouncer が接続をプールするため、多数のアプリケーションプロセスやサーバーレスインスタンスで少数の Postgres バックエンドを共有できます。
Prisma CLI (Prisma Migrate) は、ポート 5432 で直接接続します。Prisma Migrate は実行中にセッションレベルのアドバイザリロックを取得します。PgBouncer のトランザクションプーリングモードでは、このロックがプールされたバックエンド上に保持されたまま、そのバックエンドが他のクライアントにも割り当てられるため、後続の移行がこのロックによってブロックされてしまいます。

モーダル上部で Directly と via PgBouncer を切り替えると、それぞれのポートを確認できます。サーバーと認証情報はどちらの接続でも共通で、異なるのはポートだけです。 via PgBouncer を選択した状態で Download CA certificate をクリックします。Directly を選択している場合は、先に Use SSL をオンにするとボタンが表示されます。ファイル名は <service-name>-ca-certificate.pem です。このファイルは Settings → CA Certificate からも取得できます。この証明書はインスタンスごとに固有で、sslmode=verify-full で接続する際に使用します。これにより、接続先が自分のサーバーであることが検証されます。

プロジェクトをセットアップする

TypeScript プロジェクトを作成し、Prisma CLI、Prisma Client、node-postgres ドライバーアダプター、dotenv をインストールします。

mkdir hello-prisma
cd hello-prisma
npm init -y
npm pkg set type=module
npm install typescript tsx @types/node @types/pg --save-dev
npm install prisma@7 --save-dev
npm install @prisma/client@7 @prisma/adapter-pg pg dotenv

prisma@7 と @prisma/client@7 は、バージョンを明示してインストールしてください。本ガイドの執筆時点では、prisma の npm latest タグは Prisma 8 のリリース候補版を指しており、本ガイドとはセットアップ方法が異なります。

tsconfig.json を作成します。

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  }
}

既存のアプリに追加する場合mkdir、npm init、tsconfig.json の手順は不要です。プロジェクト内で npm install tsx @types/pg prisma@7 --save-dev と npm install @prisma/client@7 @prisma/adapter-pg pg dotenv を実行してから、Prisma の初期化に進んでください。

Prisma を初期化する

prisma init を実行する

npx prisma init --datasource-provider postgresql --output ../generated/prisma

このコマンドを実行すると、prisma/schema.prisma と Prisma の設定ファイル prisma7.config.ts が作成され、.env にはプレースホルダーの DATABASE_URL が、.gitignore には生成されたクライアントが追加されます (これらのファイルが存在しない場合は新規作成されます) 。あわせて、AI コーディングエージェント向けの Prisma スキルも追加されます。Prisma 7.10 以降では、Prisma 8 のフォーマットとの競合を避けるため、設定ファイル名が prisma7.config.ts になっています。

CA 証明書を追加する

ダウンロードした CA 証明書をプロジェクトのルートに移動し、ca-certificate.pem にリネームします。

mv ~/Downloads/<service-name>-ca-certificate.pem ca-certificate.pem

証明書の相対パスは、コマンドを実行したディレクトリを基準に解決されます。そのため、このガイドのコマンドはすべてプロジェクトのルートで実行してください。

接続を設定する

データベースを作成する

アプリ用のデータベースを作成します。<PASSWORD> とホストは、Connect モーダルに表示される値に置き換えてください。

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_prisma;"

CREATE DATABASE

接続 URL を設定する

.env で、prisma init が追加したプレースホルダーの DATABASE_URL を、次の 2 つの接続 URL に置き換えます。どちらも guide_prisma データベースを指します。パスワードには Connect モーダルに表示されるものを使用してください。

# Prisma Client（アプリ）: PgBouncer 経由、ポート 6432
DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:6432/guide_prisma?sslmode=verify-full&sslrootcert=ca-certificate.pem"

# Prisma CLI（移行）: 直接接続、ポート 5432
DIRECT_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_prisma?sslmode=require&sslaccept=strict&sslcert=ca-certificate.pem"

2 つの URL はそれぞれ別のドライバーが読み取るため、TLS パラメータの指定方法が異なります。

DATABASE_URL は、@prisma/adapter-pg 経由で node-postgres が読み取ります。Connect モーダルに表示されるものと同じ、標準の sslmode=verify-full&sslrootcert=... パラメータに対応しています。
DIRECT_URL は、Prisma CLI のスキーマエンジンが読み取ります。このエンジンは独自のパラメータを使用し、sslcert で CA 証明書へのパスを指定し、sslaccept=strict で証明書とホスト名の検証を有効にします。

Prisma CLI 用の URL には sslmode=verify-full&sslrootcert=... を使用しないでください。スキーマエンジンは sslrootcert を無視するため、sslaccept=strict を指定しないとサーバー証明書の検証がまったく行われません。その結果、接続は暗号化されても認証はされない状態になります。

Prisma CLI が直接接続を使用するよう設定する

prisma7.config.ts の内容を次のように置き換えます。

import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DIRECT_URL"),
  },
});

Prisma 7 では、設定ファイル内の URL は CLI だけが使用します。Prisma Client はドライバーアダプターから接続を取得します。ドライバーアダプターの設定はデータベースにクエリを実行するで行います。

スキーマを定義して移行を実行する

モデルを追加する

prisma/schema.prisma の末尾に Todo モデルを追加します。

model Todo {
  id        Int      @id @default(autoincrement())
  title     String
  done      Boolean  @default(false)
  createdAt DateTime @default(now())
}

マイグレーションを実行する

Linux では、Prisma Migrate を直接実行します。

npx prisma migrate dev --name init

macOS では、同じコマンドを Linux コンテナー内で実行します。

docker run --rm -it -v "$PWD":/app -w /app node:24 npx prisma migrate dev --name init

ClickHouse Managed Postgres は TLS 1.3 のみをサポートしています。macOS では、Prisma CLI のスキーマエンジンがシステムの TLS ライブラリを使用するため、この条件では接続できません。P1011: Error opening a TLS connection: One or more parameters passed to a function were not valid というエラーで失敗するか、sslcert を削除した場合は bad protocol version というエラーで失敗します (prisma/orm#29600) 。この問題が影響するのは、prisma migrate や prisma db pull など、データベースに接続する CLI コマンドのみです。Prisma Client は node-postgres 経由で接続するため、影響を受けません。この問題は、CLI を Linux コンテナー内、または Linux ベースの CI パイプライン内で実行することで回避できます。

Prisma は prisma/migrations/ に SQL の移行ファイルを作成し、適用します。

Applying migration `20260930165244_init`

The following migration(s) have been created and applied from new schema changes:

prisma/migrations/
  └─ 20260930165244_init/
    └─ migration.sql

Your database is now in sync with your schema.

Prisma Client を生成する

npx prisma generate

クライアントは generated/prisma に生成されます。このコマンドはデータベースに接続しないため、どのプラットフォームでも実行できます。

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

Prisma Client を作成する

lib/prisma.ts を作成します。PrismaPg アダプターは、DATABASE_URL を使用して PgBouncer 経由で接続します。

import "dotenv/config";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "../generated/prisma/client";

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });

export const prisma = new PrismaClient({ adapter });

PgBouncer の設定は不要@prisma/adapter-pg は各クエリを名前なしのプリペアドステートメントとして送信し、DEALLOCATE を一切実行しないため、PgBouncer のトランザクションプーリングモードでも問題なく動作します。プールされた複数のバックエンドで数百種類のクエリを同時実行しても、エラーは発生しません。旧バージョンの Prisma で使われていた pgbouncer=true URL パラメータは不要で、ドライバーアダプターでは指定しても効果はありません。

CRUD クエリを実行する

script.ts を作成します。

import { prisma } from "./lib/prisma";

async function main() {
  // 作成
  const todo = await prisma.todo.create({
    data: { title: "Connect Prisma to ClickHouse Managed Postgres" },
  });
  console.log("Created:", todo);

  // 読み取り
  const open = await prisma.todo.findMany({ where: { done: false } });
  console.log("Open todos:", open.length);

  // 更新
  const updated = await prisma.todo.update({
    where: { id: todo.id },
    data: { done: true },
  });
  console.log("Updated:", updated);

  // 削除
  await prisma.todo.delete({ where: { id: todo.id } });
  console.log("Deleted todo", todo.id);
}

main().finally(() => prisma.$disconnect());

スクリプトを実行します。

npx tsx script.ts

Created: {
  id: 1,
  title: 'Connect Prisma to ClickHouse Managed Postgres',
  done: false,
  createdAt: 2026-09-30T16:52:57.116Z
}
Open todos: 1
Updated: {
  id: 1,
  title: 'Connect Prisma to ClickHouse Managed Postgres',
  done: true,
  createdAt: 2026-09-30T16:52:57.116Z
}
Deleted todo 1

HTTP でデータを配信する

server.ts を作成します。これは、POST /todos で todo を作成し、すべての GET リクエストに対して todo の一覧を返す最小構成の HTTP サーバーです。

import { createServer } from "node:http";
import { prisma } from "./lib/prisma";

const port = Number(process.env.PORT ?? 3000);

createServer(async (req, res) => {
  if (req.method === "POST" && req.url === "/todos") {
    let body = "";
    for await (const chunk of req) body += chunk;
    const todo = await prisma.todo.create({ data: { title: JSON.parse(body).title } });
    res.writeHead(201, { "Content-Type": "application/json" });
    res.end(JSON.stringify(todo));
    return;
  }

  const todos = await prisma.todo.findMany({ orderBy: { id: "asc" } });
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify(todos, null, 2));
}).listen(port, () => console.log(`Listening on http://localhost:${port}`));

サーバーを起動します。

npx tsx server.ts

別の端末を開き、todo を 2 件追加します。

curl -X POST localhost:3000/todos -H "Content-Type: application/json" -d '{"title": "Try Prisma with ClickHouse Managed Postgres"}'
curl -X POST localhost:3000/todos -H "Content-Type: application/json" -d '{"title": "Add a read replica"}'

ブラウザで http://localhost:3000/todos を開くと、追加した todo を確認できます。レスポンスは次のようになります。

[
  {
    "id": 2,
    "title": "Try Prisma with ClickHouse Managed Postgres",
    "done": false,
    "createdAt": "2026-09-30T16:53:06.098Z"
  },
  {
    "id": 3,
    "title": "Add a read replica",
    "done": false,
    "createdAt": "2026-09-30T16:53:06.184Z"
  }
]

SQL コンソールで確認する

ClickHouse Cloud コンソールで対象サービスの SQL console を開き、データベースと public スキーマを展開して Todo テーブルを選択します。あわせて _prisma_migrations テーブルも表示されます。これは、Prisma Migrate が適用済みの移行を記録するテーブルです。 Todo テーブルには、HTTP エンドポイント経由で追加した 2 行が格納されています。

id	title	done	createdAt
2	Try Prisma with ClickHouse Managed Postgres	false	2026-09-30 16:53:06.098
3	Add a read replica	false	2026-09-30 16:53:06.184

トラブルシューティング

エラー	原因と対処法
`P1011: Error opening a TLS connection: One or more parameters passed to a function were not valid` または `bad protocol version`	Prisma CLI が macOS 上で実行されています。移行を実行するで示しているように、Linux コンテナー内で実行してください。
`P1011: ... certificate verify failed`	Prisma CLI がサーバーを検証できていません。`DIRECT_URL` の `sslcert` が、インスタンスの CA 証明書を指しているか確認してください。
`P1011: ... cert file not found`	`DIRECT_URL` の `sslcert` に指定したパスが正しくありません。プロジェクトのルートから CLI を実行するか、絶対パスを指定してください。
`unable to verify the first certificate`	Prisma Client がサーバーを検証できていません。`DATABASE_URL` の `sslrootcert` が、インスタンスの CA 証明書を指しているか確認してください。
`ENOENT: no such file or directory`	`DATABASE_URL` の `sslrootcert` に指定したパスが正しくありません。プロジェクトのルートからアプリケーションを実行するか、絶対パスを指定してください。

次のステップ

接続: 接続文字列、PgBouncer、TLS
設定: Postgres と PgBouncer のパラメータをチューニングする
読み取りレプリカ: 読み取り負荷の高いワークロードをスケールさせる
ローカル開発: Docker 上のローカル Postgres を使って開発する
本番環境での Prisma Migrate: CI パイプラインで prisma migrate deploy を使用する

はじめる

機能

ガイド

料金

ClickHouse 連携

移行

監視

よくある質問

ClickHouse Managed Postgres で Prisma を使用する

前提条件

ClickHouse Managed Postgres サービスを作成する

接続情報を取得する

プロジェクトをセットアップする

Prisma を初期化する

接続を設定する

スキーマを定義して移行を実行する

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

SQL コンソールで確認する

トラブルシューティング

次のステップ

​前提条件

​ClickHouse Managed Postgres サービスを作成する

​接続情報を取得する

​プロジェクトをセットアップする

​Prisma を初期化する

​接続を設定する

​スキーマを定義して移行を実行する

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

​SQL コンソールで確認する

​トラブルシューティング

​次のステップ

前提条件

ClickHouse Managed Postgres サービスを作成する

接続情報を取得する

プロジェクトをセットアップする

Prisma を初期化する

接続を設定する

スキーマを定義して移行を実行する

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

SQL コンソールで確認する

トラブルシューティング

次のステップ