kotlin-exposed-patternsでKotlinのDB処理を整える

使うとこうなる

kotlin-exposed-patternsを入れると、エージェントはExposedのコードを毎回同じ型で組み立てるようになります。たとえば次のように頼んだとしましょう。

Exposedでユーザー検索とページ分割を実装して

エージェントはテーブル定義、検索関数、ページ情報を持つデータクラスをまとめて返します。各関数はnewSuspendedTransactionのブロックで囲まれ、コルーチン（Kotlinの非同期処理の仕組み）の中でも安全に動く形です。検索語はLIKEの特殊文字をエスケープしてから使うため、利用者の入力で意図しない一致が起きません。

ページ分割の結果は、次の項目を持つPageクラスで受け取ります。

項目	内容
data	そのページのレコード一覧
total	全体の件数
page / limit	現在のページ番号と1ページの件数
totalPages	総ページ数
hasNext / hasPrevious	次・前のページがあるか

このスキルはGitHubのaffaan-m/ECCで公開されていて、リポジトリのスターは288823です。中身はSKILL.mdの1ファイルで、ユーザーと注文を題材にしたコード例が中心になっています。

kotlin-exposed-patternsでできること

このスキルは、Exposedでのデータアクセスを4つの面から支えます。「クエリ」「接続と構造変更」「トランザクション」「分離とテスト」です。エージェントはこれらの例を手元のテーブルに当てはめてコードを書きます。

検索・更新クエリをDSLとDAOで書く

Exposedには2つの書き方があり、スキルは両方の例を載せています。使い分けの目安は次のとおりです。

書き方	特徴	向く場面
DSL	SQLに近い式で書く	単純な検索や更新
DAO	レコードをオブジェクトとして扱う	作成・更新などエンティティの状態を管理したいとき

DSLの例は、登録・取得・更新・削除の基本操作から、テーブル結合・集計・サブクエリ・ページ分割までそろっています。複数件をまとめて入れるbatchInsertや、重複時に更新へ切り替えるupsertも対象です。PostgreSQLのJSONB列をkotlinx.serializationで読み書きする列型の定義も含まれます。

接続の再利用と構造変更を管理する

接続まわりは、HikariCPのコネクションプール（接続を使い回す仕組み）とFlywayのマイグレーションを組み合わせる構成です。HikariCPでは最大接続数、自動コミットの無効化、分離レベルREAD_COMMITTEDを指定します。Flywayはアプリの起動時に、番号付きのSQLファイルを順に適用してテーブル構造をそろえます。

マイグレーションのSQLは、src/main/resources/db/migration/にV1__create_users.sqlのような名前で置く形です。起動処理では、マイグレーションを先に実行してから接続プールを作ります。

トランザクションで処理をまとめる

**すべてのデータベース操作をnewSuspendedTransactionのブロック内で実行するのが、このスキルの原則です。**ブロック内の処理は、まとめて成功するか、まとめて失敗します。送金のように2件の更新を同時に通したい場面の例や、SERIALIZABLEなど分離レベルを変える例もあります。

データアクセスを分けてテストする

業務処理とデータアクセスを切り離すために使うのが、リポジトリパターン（データの出し入れを1つの窓口にまとめる設計）です。UserRepositoryというインターフェースに検索・作成・更新・削除・件数取得を定義し、Exposedでの実装クラスを別に用意する形です。テストではH2のメモリ上データベースをPostgreSQL互換モードで起動し、実装クラスをそのまま検証します。

テスト例は3つあります。作成したユーザーを取得できるか、未登録のメールでnullが返るか、25件を10件ずつ分けたページ情報が正しいかの確認です。各テストの前にテーブルを空にするので、テスト同士が影響し合いません。

インストール方法

インストールは、コマンドで入れる方法とエージェントに頼む方法の2通りです。コマンドを実行すると、Claude CodeやCodexなど入れる先のエージェントを選べます。

npx skills add https://github.com/affaan-m/ECC --skill kotlin-exposed-patterns

エージェントに任せる場合は、次の文面をそのまま送ってください。中身の確認から配置までをまとめて頼む内容です。

次の Agent Skill をインストールしてください。
https://github.com/affaan-m/ECC/tree/main/skills/kotlin-exposed-patterns

まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/kotlin-exposed-patterns/、Codex なら ~/.agents/skills/kotlin-exposed-patterns/ に配置してください。

置き場所は、エージェントの種類とスキルを使う範囲で決まります。

エージェント	すべてのプロジェクトで使う	特定のプロジェクトだけで使う
Claude Code	~/.claude/skills/	プロジェクトの.claude/skills/
Codex	~/.agents/skills/	プロジェクトの.agents/skills/

Exposedを使うプロジェクトが1つだけなら、プロジェクト側に置く方法が向いています。

使い方の例

依頼文には、テーブルの中身や接続先など手元の条件を添えてください。そうすると、返ってくるコードがその条件に沿ったものになります。

PostgreSQLにつなぐ接続設定をHikariCPとFlywayで作って。プールの最大数は10にして

返ってくるのは、接続情報をまとめるデータクラス、HikariCPからExposedのDatabaseを作るファクトリー、Flywayを実行する関数です。最初のマイグレーションSQLと、起動時にマイグレーションを実行してから接続する処理も付きます。

注文テーブルを追加して、指定したユーザーの注文を新しい順に一覧で取る処理を書いて

ユーザーテーブルを参照する注文テーブルの定義と、2つのテーブルをinnerJoinで結合する検索関数が返ります。並び順は作成日時の降順です。スキルの例に沿うと、結果は注文ID・状態・金額・ユーザー名を持つデータクラスに詰められます。

データアクセスをインターフェースで分離し、H2でテストして

そろうのは、リポジトリのインターフェース、Exposedでの実装クラス、H2を使うテストコードの3点です。テストはFunSpec形式で、各テストの前にテーブルを空にする処理が入ります。

注意点

このスキルはパターン集なので、バージョンや接続先はプロジェクトに合わせて自分で確かめる必要があります。資料のGradle設定は次のバージョンを前提にしています。

ライブラリ	資料のバージョン
Exposed（core、dao、jdbc、kotlin-datetime、json）	1.0.0
PostgreSQLドライバー	42.7.5
HikariCP	6.2.1
Flyway（core、database-postgresql）	10.22.0
H2（テスト用）	2.3.232

手元のバージョンが違う場合は、依頼文でバージョンを伝えてから書かせてください。生成されたコードは、ビルドとテストを通してから取り込むのが安全です。

**設定例とSQLはPostgreSQLを前提にしています。**JSONB列やgen_random_uuid()による主キーの生成、PGobjectを使った変換は、PostgreSQL固有の書き方です。ほかのデータベース製品向けの設定例はスキルに含まれていません。

接続先のURL・ドライバー・ユーザー名・パスワードは、自分の環境に合わせて用意します。スキルの例では、これらをアプリの設定ファイルから読み込む形です。認証情報をコードに直接書かないよう気をつけてください。

ライセンスはMITで、含まれるファイルはSKILL.mdだけです。スクリプトは入っていません。それでも、入れる前にSKILL.mdを開いて内容を一度確認しておくと安心です。

まとめ

kotlin-exposed-patternsは、JetBrains Exposedを使ったKotlinのデータベース処理を、クエリからテストまで1つの型にそろえるためのスキルです。対象はDSLとDAOのクエリ、HikariCPとFlywayの接続設定、リポジトリの分離とH2でのテストです。どれもエージェントが同じパターンで提案できるようになります。PostgreSQLとExposedでサーバーサイドを書いている人ほど、そのまま使える部分が多いスキルです。インストール先や紹介文はcccskillsのページで確認できます。