Better Authのスキーママイグレーション管理の仕組み
Better Auth はどうやってDBアダプタごとのスキーママイグレーションを扱っているのか？
この記事では、Better AuthというTypeScript向け認証・認可ライブラリのスキーママイグレーション管理について解説します。開発者Beka Cruさんが実装した仕組みを見ていきましょう。
Better Authは、TypeScript向けの包括的な認証・認可ライブラリで、様々なデータベースやフレームワークに対応しています。今回は、Better Authがどのようにして多様なDBアダプタ（Kysely、Prisma、Drizzleなど）に対応し、スキーママイグレーションを管理しているのかを解説します。
なぜスキーマ管理が重要なのか
認証ライブラリにとって、ユーザー情報やセッションデータなどを格納するデータベーススキーマの管理は非常に重要です。特にBetter Authのようにプラグインによって必要なスキーマが動的に変わる場合、その管理はさらに複雑になります。
Better Authのスキーマ管理の基本構造
Better Authのスキーマ管理は、以下の要素を組み合わせて実現しています：
1. スキーマ定義の集約
Better Authでは、様々な場所からスキーマ定義を集約しています：
-
コア機能:
user、session、account、verificationといった基本テーブルのスキーマ定義 -
プラグイン: 有効化されたプラグイン（
twoFactor、organization、passkey、apiKeyなど）が追加するスキーマ定義 - ユーザー設定: デフォルトのテーブル名やフィールド名のカスタマイズ、独自フィールドの追加
これらすべてのスキーマ情報はBetter Auth内部でマージされ、最終的に必要となる完全なスキーマを構築します。
2. CLIによる処理 (@better-auth/cli)
@better-auth/cliは次のような流れで動作します：
- ユーザーのプロジェクトからBetter Authの設定ファイル（
auth.tsなど）を読み込み - 使用中のDBアダプタとプラグイン、カスタマイズ情報を解析
- 解析結果と内部スキーマ定義を元に、選択されたアダプタに応じた処理を実行
アダプタ別のアプローチ
主要なアダプタごとに、具体的にどのようにスキーマ管理を行っているのかを見ていきましょう。
1. Kysely（ビルトインアダプタ）
Better Authは内部的にKyselyを使用して、SQLite、PostgreSQL、MySQL、MSSQLなどのRDBMSに対応しています。
generateコマンドの動作
- 集約されたスキーマ情報を元に、**SQLマイグレーションファイル（
.sql）**を生成 -
CREATE TABLE文やALTER TABLE文を含む適切なSQLを出力 - 主に
packages/better-auth/src/db/get-migration.tsとpackages/cli/src/generators/kysely.tsで実装
migrateコマンドの動作
- 生成されたSQLをデータベースに直接適用
- ユーザーは追加ツールなしでスキーマを最新状態に保てる
メリット・デメリット
- メリット: CLIだけでスキーマ生成から適用まで完結して手軽
- デメリット: ORM固有の機能（Prismaのリレーション構文など）は利用できない
2. Prisma
Prismaは型安全なデータベースアクセスを提供する人気のORMです。
generateコマンドの動作
- 既存の
schema.prismaファイルを解析し、必要なモデルやフィールドを追記・更新 -
@mrleebo/prisma-astなどを使用してPrismaスキーマをASTとして安全に編集 - ユーザー設定は
@map属性を使って反映 - 主に
packages/cli/src/generators/prisma.tsで実装
migrateコマンドの動作
- サポートされていません
- ユーザー自身がPrisma CLI（
prisma migrate devやprisma db push）を実行する必要あり
メリット・デメリット
- メリット: Prismaの型安全性やマイグレーション機能を最大限活用可能
- デメリット: スキーマ適用はPrisma CLIに依存するため、Better Auth CLIだけでは完結しない
3. Drizzle
Drizzle ORMは軽量で高速、型安全なTypeScript ORMです。
generateコマンドの動作
- Drizzle ORMのスキーマ定義ファイル（
.ts）を生成・更新 - データベース種類に応じて
pgTable、mysqlTable、sqliteTableなどを使い分け - フィールドの型、NULL許容、ユニーク制約なども適切に出力
- 主に
packages/cli/src/generators/drizzle.tsで実装
migrateコマンドの動作
- サポートされていません
- ユーザー自身がDrizzle Kit（
drizzle-kit generateなど）を実行する必要あり
メリット・デメリット
- メリット: Drizzleの型安全性やDrizzle Kitによるマイグレーション管理を活用可能
- デメリット: スキーマ適用はDrizzle Kitに依存するため、Better Auth CLIだけでは完結しない
まとめ：アダプタ別のスキーマ管理方法
Better Authのスキーママイグレーション生成は、使用するDBアダプタに応じて最適なアプローチを提供します。
| アダプタ |
generateコマンドの出力 |
migrateコマンドの機能 |
適用方法 |
|---|---|---|---|
| Kysely (ビルトイン) | SQLマイグレーションファイル (.sql) |
SQLをDBに直接適用 | npx @better-auth/cli migrate |
| Prisma | Prismaスキーマ (schema.prisma) の更新 |
なし |
prisma migrate devまたはprisma db push
|
| Drizzle | Drizzleスキーマ (.ts) の更新 |
なし |
drizzle-kit generateとdrizzle-kit migrate
|
このように、Better Authは各データベース/ORMのエコシステムを尊重しつつ、プラグインによるスキーマ拡張にも対応できる柔軟な仕組みを提供しています。これにより、私たち開発者は自身が選択した技術スタックでスムーズにBetter Authを導入・運用できます。
より詳しい情報はBetter Authの公式ドキュメントをご覧ください。この記事が皆さんのお役に立てば幸いです！
Discussion