カテゴリー

RustエンジンレスなPrisma/SQLiteクライアントを外部モジュールとして利用する

※ 当ページには【広告/PR】を含む場合があります。
2025/07/01
【Prisma入門】ローカル環境できるPrismaを使い始めたい人のためのRDB操作ガイド
蛸壺の技術ブログ｜RustエンジンレスなPrisma/SQLiteクライアントを外部モジュールとして利用する
目次



Prismaを利用する外部の何らかのモジュールを別のプロジェクトへ持ち込む際に問題となってくるのが、RustでビルドされたPrisma固有の「クライアントエンジン」の存在です。
例えば、Prismaクライアントを外部のプロジェクトへ持ち込む際に、このクライアントエンジンが存在しない場合、 

            #...

PrismaClientInitializationError: Prisma Client could not locate the Query Engine for runtime "debian-openssl-3.0.x".

This is likely caused by a bundler that has not copied "libquery_engine-debian-openssl-3.0.x.so.node" next to the resulting bundle.
Ensure that "libquery_engine-debian-openssl-3.0.x.so.node" has been copied next to the bundle or in "prisma/client".

といったエラーが発生します。
このエラーが起こった場合、実行環境に合ったバイナリファイルを個別に読み込むように適当な場所に配置する必要があります。

これまでこの手動でバイナリエンジンファイルを用意する手順が面倒で、忘れるとPrismaがうまく動作しない原因の一つとなっていました。

このため、 v6.7.0 からはRustエンジンの有無が、SQLiteとPostgreSQLで選択的に選べるように変更されました。
このRustエンジンに代わる新しい仕組みを「ドライバーアダプタ」と呼ぶようです。

参考｜driver adapters
以下の内容で、この新しい仕組みを試す方法を紹介していきます。

合同会社タコスキングダム｜蛸壺の技術ブログJavascript(js)＆Typescript(ts)プログラミング入門〜これから学ぶ人のためのおすすめ書籍＆教材の手引き

ドライバーアダプタの導入方法



ではここからドライバーアダプタを導入していきます。
ドライバーアダプタはPrisma v6.7.0以降でしか利用できませんので、現時点でインストールしてあるPrismaのバージョンを確認します。
一例ですが、動作確認時点の著者の環境は以下の通りです。 


            $ npx prisma --version
Environment variables loaded from .env
Prisma schema loaded from prisma/schema.prisma
prisma                  : 6.10.1
@prisma/client          : 6.10.1
Computed binaryTarget   : debian-openssl-3.0.x
Operating System        : linux
Architecture            : x64
Node.js                 : v24.3.0
TypeScript              : 5.8.3
Query Engine (Node-API) : libquery-engine 9b628578b3b7cae625e8c927178f15a170e74a9c (at node_modules/@prisma/engines/libquery_engine-debian-openssl-3.0.x.so.node)
PSL                     : @prisma/prisma-schema-wasm 6.10.1-1.9b628578b3b7cae625e8c927178f15a170e74a9c
Schema Engine           : schema-engine-cli 9b628578b3b7cae625e8c927178f15a170e74a9c (at node_modules/@prisma/engines/schema-engine-debian-openssl-3.0.x)
Default Engines Hash    : 9b628578b3b7cae625e8c927178f15a170e74a9c
Studio                  : 0.511.0

Prismaスキーマの修正



まずはクライアントのアーキテクチャに driverAdapters と queryCompiler を指定します。 

            generator client {
  provider        = "prisma-client-js"
  //👇これを追記
  previewFeatures = ["queryCompiler", "driverAdapters"]
}

//...

スキーマを修正したらPrismaクライアントの再構築しておきます。 

            $ npx prisma generate

なお、SQLiteの場合、 --no-engine オプションをつけると、利用時にエラーが起きるので注意しましょう。


ドライバーアダプタのインストール



現在、ドライバーアダプタのモジュールライブラリは別提供です。
また、SQLiteとPostgreSQLでも利用できるパッケージが別なので注意が必要です。
SQLite向けのドライバーアダプタは以下のようにインストールします。 

            $ yarn add better-sqlite3 @prisma/adapter-better-sqlite3
$ yarn add -D @types/better-sqlite3

これでSQLite用のドライバーアダプタを使う準備が整いました。
ここからコードで実装する際には、以下のようにPrismaクライアントを初期化を修正しましょう。 


            import { PrismaClient } from '@prisma/client';
import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3';

if (!process.env.DATABASE_URL) {
    throw new Error('DATABASE_URL environment variable is not set.');
}
const adapter = new PrismaBetterSQLite3({ url: process.env.DATABASE_URL as string });
const prisma = new PrismaClient({ adapter });

//...通常のprismaクライアントの操作

これでRustバイナリなしでもPrismaクライアントが読み込めるようになりました。

合同会社タコスキングダム｜蛸壺の技術ブログJavascript(js)＆Typescript(ts)プログラミング入門〜これから学ぶ人のためのおすすめ書籍＆教材の手引き

Prismaクライアントを含むライブラリを外部の別プロジェクトへ持ち込む



先程までの内容で、RustエンジンレスなPrismaクライアントが問題なく動作することが確認できました。
そのプロジェクトの中でゴリゴリとPrismaを使うのであれば問題なく使えるのですが、パッケージビルドして、別のNodejsプロジェクトからPrismaクライアントを使うためにはもう少し手順が必要です。

たしかにRustエンジンは不要になったが...



例えば、Prismaクライアントを含むバンドルしたライブラリを利用して別のプロジェクトからPrismaメソッドをそのまま呼び出すと... 


            node:fs:554
  return binding.open(
                 ^

Error: ENOENT: no such file or directory, open '/usr/src/app/prisma/client/query_compiler_bg.wasm'
#...
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/usr/src/app/prisma/client/query_compiler_bg.wasm'
}

と、こういったエラーが起こります。
この場合、 query_compiler_bg.wasm というWASMバイナリファイルが別途必要にはなるのでした。
Rustエンジンレスとは言っても、結局、実態はRustエンジンからWebAssemblyのバイナリなどへシフトしただけで、ビルドした生成物で完結しないことに留意が必要です。
それでもファイルはサイズ的に2MB程度ですので、Rustエンジンファイルと比べればかなり軽量で、これがRustエンジンレスする際の最大のメリットと言えるでしょう。
なお、 query_compiler_bg.wasm はPrismaクライアントコードを出力したフォルダにありますので、Prismaクライアントが検索している場所(ここでは /usr/src/app/prisma/client 以下)に手動でコピーすると良いでしょう。


合同会社タコスキングダム｜蛸壺の技術ブログJavascript(js)＆Typescript(ts)プログラミング入門〜これから学ぶ人のためのおすすめ書籍＆教材の手引き

better_sqlite3.nodeを準備する



Prismaクライアントが生成する query_compiler_bg.wasm があれば動くかというと、実はもう一つ重要なNodeネイティブランタイムが必要になります。
このファイルが無い場合には以下のようなエラーが起こります。 

            Error: Could not locate the bindings file. Tried:
 → /usr/src/app/build/better_sqlite3.node
 → /usr/src/app/build/Debug/better_sqlite3.node
 → /usr/src/app/build/Release/better_sqlite3.node
 → /usr/src/app/out/Debug/better_sqlite3.node
 → /usr/src/app/Debug/better_sqlite3.node
 → /usr/src/app/out/Release/better_sqlite3.node
 → /usr/src/app/Release/better_sqlite3.node
 → /usr/src/app/build/default/better_sqlite3.node
 → /usr/src/app/compiled/24.3.0/linux/x64/better_sqlite3.node
 → /usr/src/app/addon-build/release/install-root/better_sqlite3.node
 → /usr/src/app/addon-build/debug/install-root/better_sqlite3.node
 → /usr/src/app/addon-build/default/install-root/better_sqlite3.node
 → /usr/src/app/lib/binding/node-v137-linux-x64/better_sqlite3.node
#...
{
  tries: [
    '/usr/src/app/build/better_sqlite3.node',
    '/usr/src/app/build/Debug/better_sqlite3.node',
    '/usr/src/app/build/Release/better_sqlite3.node',
    '/usr/src/app/out/Debug/better_sqlite3.node',
    '/usr/src/app/Debug/better_sqlite3.node',
    '/usr/src/app/out/Release/better_sqlite3.node',
    '/usr/src/app/Release/better_sqlite3.node',
    '/usr/src/app/build/default/better_sqlite3.node',
    '/usr/src/app/compiled/24.3.0/linux/x64/better_sqlite3.node',
    '/usr/src/app/addon-build/release/install-root/better_sqlite3.node',
    '/usr/src/app/addon-build/debug/install-root/better_sqlite3.node',
    '/usr/src/app/addon-build/default/install-root/better_sqlite3.node',
    '/usr/src/app/lib/binding/node-v137-linux-x64/better_sqlite3.node'
  ],
  clientVersion: '6.10.1'
}

Prismaクライアントは、現在のプロジェクトルート( /usr/src/app )から見て、 build フォルダなど、いくつかの場所を検索しますが、これらのどこにも better_sqlite3.node が無い場合にはエラーが起こります。
Prismaのドライバーアダプタは better_sqlite3 で動作しているため、このバイナリファイルがどこにもないと動かすことができません。
逆に言うと、これらの該当フォルダのどれかに better_sqlite3.node をコピーするだけでOKです。
なお、このファイルは、better-sqlite3をパッケージインストールした際にビルドされるため、node_modulesの中に存在しています。 


            $ ls node_modules/better-sqlite3/build/Release/
better_sqlite3.node

DBファイルを配置する



では先程までで、外部からRustエンジンレスのPrismaクライアントを使うバイナリを準備したので、データベース本体もプロジェクトにコピーしてきます。
あとはデータベースを置いた先を DATABASE_URL で指定すれば良いのですが、指定の際に相対パス・ ./dev.db のままだと、どこを指定しているのか曖昧になります。 (Prismaスキーマファイルのある場所からの相対パスを意味するため)
ということで、外部でPrismaクライアントを使う際の DATABASE_URL は必ず手元の環境に合わせた 絶対パス で指定しましょう。
例えば、絶対パスで /usr/src/app/data 以下に配置した場合、 

            #DATABASE_URL=file:./dev.db
DATABASE_URL=file:/usr/src/app/data/dev.db

というように .env を書き直します。
問題がなければ、Prismaクライアントが動作するはずです。

合同会社タコスキングダム｜蛸壺の技術ブログJavascript(js)＆Typescript(ts)プログラミング入門〜これから学ぶ人のためのおすすめ書籍＆教材の手引き

まとめ



今回は、話題の「Rustエンジンレス」なPrismaクライアントを使ってSQLiteを操作する設定手順を確認していきました。
PrismaでSQLiteかPostgreSQLを利用してきたDB設計者には、WASMベースのドライバーアダプタが今後有用なアーキテクチャになってくると思います。
移行にさほど難しい手順はないので、この際サクッとRustエンジンレスに変更してみるのも良いでしょう。

【Prisma入門】ローカル環境できるPrismaを使い始めたい人のためのRDB操作ガイド
記事を書いた人

記事の担当:taconocat

ナンデモ系エンジニア

主にAngularでフロントエンド開発することが多いです。 開発環境はLinuxメインで進めているので、シェルコマンドも多用しております。 コツコツとプログラミングするのが好きな人間です。

カテゴリー
合同会社タコスキングダム｜蛸壺の技術ブログJavascript(js)＆Typescript(ts)プログラミング入門〜これから学ぶ人のためのおすすめ書籍＆教材の手引き