Announcing TypedSQL: Make your raw SQL queries type-safe with Prisma ORM

TL;DR: 生のSQLを完全にタイプセーフにしました

Prisma ORMでは、ほとんどのアプリの95%を占める一般的なCRUDクエリを記述するための、最高のAPIであると確信しているものを設計しました！

残りの5%—Prisma Client APIで表現できない複雑なクエリや、最大限のパフォーマンスを必要とするクエリ—に対しては、生のSQLを記述するための低レベルAPIを提供していました。しかし、このエスケープハッチはタイプセーフティを提供せず、開発者はPrisma ORMに慣れ親しんだ素晴らしいDXを失っていたため、より良い方法を探しました！

本日のPrisma ORM v5.19.0リリースで、TypedSQLを発表できることを大変嬉しく思います。TypedSQLは、複雑でパフォーマンスの高いクエリを記述する最良の方法です。TypedSQLはただのSQLですが、より優れています。完全にタイプセーフで、自動補完を提供し、生のSQLクエリを作成する必要がある場合に素晴らしいDXを提供します。その仕組みは以下のとおりです

1. .sqlファイルにSQLクエリを記述し、prisma/sqlディレクトリに配置します

   生のSQLPrismaスキーマ

   引数付きのSQLクエリを作成することもできます！

   生のSQLPrismaスキーマ

2. prisma generateで--sqlフラグを使用してクエリ関数を生成します

3. @prisma/client/sqlからクエリ関数をインポートし…

   …新しい$queryRawTyped関数内でそれを呼び出すと、完全に型付けされた結果が得られます😎

   SQLクエリに引数がある場合、それらは$queryRawTypedに渡されるクエリ関数に提供されます

Prisma Client APIとTypedSQLを組み合わせることで、CRUD操作と非常に複雑なクエリの両方で最高の体験を提供します。この追加により、皆様が二度とSQLクエリビルダーに触れる必要がなくなることを願っています！

高い生産性のための高レベル抽象化

生のSQLは、リレーショナルデータベースでデータをクエリするための最も強力で柔軟な方法を依然として提供します。しかし、いくつかの欠点も伴います。

生のSQLの欠点

以前にTypeScriptプロジェクトで生のSQLを記述したことがあるなら、それが最高のDXを提供しないことをご存知でしょう。

• SQLクエリ記述時の自動補完がない。
• クエリ結果のタイプセーフティがない。
• 複雑なSQLクエリの記述とデバッグの複雑さ。
• 開発チームはしばしばSQLの経験レベルが異なり、チームの全員がSQLの記述に熟練しているわけではありません。
• SQLはTypeScript（オブジェクト）とは異なるデータモデル（リレーション）を使用しており、これらを相互にマッピングする必要があります。これは特に、SQLでは外部キーとして表現されるモデル間のリレーションシップが、TypeScriptではネストされたオブジェクトとして表現される場合に顕著です。

アプリケーション開発者はSQLではなく、**データ**に注力すべき

Prismaでは、アプリケーション開発者はSQLではなく、**データ**に注力すべきであると強く信じています。

典型的なアプリケーション開発者が記述するクエリのほとんどは、ページネーション、フィルター、ネストされたクエリなどの一般的なCRUD操作に関連する、かなり限られた機能セットを使用します。

私たちの主な目標は、アプリケーション開発者がクエリやデータベースの行からコード内のオブジェクトへのマッピングについてあまり考えることなく、必要なデータを迅速に取得できるようにすることです。

Prisma ORMで迅速に開発・リリース

これが、私たちがPrisma ORMを構築した理由です。開発者が生産的になり、迅速にリリースできるようにする抽象化を提供するためです！Prisma ORMを使用する典型的なワークフローの概要を次に示します。

まず、人間が読みやすいスキーマでデータモデルを定義します

Prisma CLIを使用して、(カスタマイズ可能な) SQLマイグレーションを生成し、データベースに対してマイグレーションを実行できます。スキーマがデータベースにマッピングされたら、Prisma Clientでクエリを実行できます

エスケープハッチ: 生のSQLへの移行

このような高レベルの抽象化が開発者の生産性を向上させると信じていますが、多くのプロジェクトで生のSQLを記述するオプションが必要とされるのを見てきました。これは通常、次のような場合に発生します。

• Prisma Client APIが特定のクエリを表現するのに十分な柔軟性がない場合。
• クエリの速度を最適化する必要がある場合。

これらの場合、Prisma ORMはPrisma Clientの$queryRawメソッドを使用することで、生のSQLに対するエスケープハッチを提供します。

このアプローチの主な問題は、このクエリがタイプセーフではないことです。開発者が標準のPrisma Client APIから得られるタイプセーフティの恩恵を受けたい場合、このクエリの戻り値を手動で記述する必要があり、これは面倒で時間がかかります。もう一つの問題は、これらの手動で定義された型がスキーマの変更によって自動更新されないため、別のエラーの可能性が生じることです。

Prisma ORMの生のクエリを使用する際のDXを向上させる方法はいくつかありますが (例: Prisma Client用のKyselyクエリビルダー拡張機能やSafeQLの使用)、私たちはこの問題をネイティブな方法で解決したいと考えました。

Prisma ORMの新機能: TypedSQL 🎉

だからこそ、生のSQLクエリにタイプセーフティをもたらすPrisma ORMの新しいワークフローであるTypedSQLを発表できることを嬉しく思います。TypedSQLは、PgTypedやsqlxのような同様のアイデアに基づいたプロジェクトからインスピレーションを受けています。

TypedSQLにより、Prisma ORMは両方の利点を提供します

• 開発者の生産性を高め、プロジェクト内のクエリの大部分に対応できる高レベルの抽象化。
• SQLを直接作成する必要がある場合に、快適でタイプセーフなエスケープハッチ。

また、個々の開発者が異なる好みを持ちがちな開発チームに対して、好きなアプローチを選択するオプションを提供します。チームに熱狂的なSQLファンがいる一方で、SQLには絶対に触れたくないという開発者もいますか？

Prisma ORMは、DXや柔軟性を犠牲にすることなく、両方のグループが望むものを提供します！

お試しいただき、フィードバックをお寄せください

TypedSQLは、過去に$queryRawの使用に頼っていた場合に、あなたの新しい相棒となります。

私たちはTypedSQLをSQLクエリビルダーの進化と捉えており、すべての抽象化を取り除くことで、開発者にデータベースクエリにおいてさらに大きな柔軟性を提供します。

TypedSQLを試す

ぜひTypedSQLをお試しいただき、XとDiscordでご意見をお聞かせください！