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スキーマの修正

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

            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エンジンレスに変更してみるのも良いでしょう。