Clione-SQL を知っていますか？
Java で DB アクセスのコードを書いたことがある人なら、検索条件の動的組み立てで苦しんだ経験があると思います。MyBatis の <if> タグ地獄、JPA の Criteria API の可読性崩壊、あるいは StringBuilder で SQL を組み立てる原始的な戦い。
そんな中で Clione-SQL というライブラリが提案したアプローチは、かなり異質でした。
SELECT * FROM employee
WHERE
dept_id = /* $dept_id */1
AND name = /* $name */'山田'
AND status = /* $status */'active'
これがそのまま SQL テンプレートです。SQL コメントの中にパラメータ名を書いて、直後にデフォルト値を置く。DB ツールでそのまま実行すればデフォルト値で動くし、アプリケーション経由ならパラメータがバインドされる。いわゆる 2way SQL です。
かゆいところに手が届く行削除の仕様
Clione-SQL の何がすごいかというと、動的な条件組み立てのルールがシンプルなのに表現力が高いところです。
$ 付きパラメータに None を渡すと、その行が丸ごと消える。たったこれだけのルールで、動的検索が実現できます。
# name を指定しない → name の行が消える
db.query(User, "search.sql", {"dept_id": 10, "name": None, "status": "active"})
-- name の行が消えて、先頭に残った AND も自動除去される
SELECT * FROM employee
WHERE
dept_id = ?
AND status = ?
さらに、インデントで親子関係が定義されるので、括弧でグルーピングした条件も自然に扱えます。
WHERE
id = /* $id */1
AND (
status = /* $status1 */'active'
OR status = /* $status2 */'pending'
)
status1 と status2 が両方 None なら、括弧ブロックごと消える。子が全部消えたら親も消える。WHERE の下の条件が全部消えたら WHERE 自体も消える。if 文を一つも書かずに、です。
IN 句もリストを渡せば自動展開されるし、空リストなら IN (NULL) になって 0 件。このへんの「あー、そうそう、そこ面倒なんだよ」というポイントを的確に潰してくれる設計が Clione-SQL の魅力だと思っています。
それを Python でも使いたかった
普段 Python でちょっとしたツールやバッチ処理を書くことが増えて、そのたびに「Clione-SQL があればなあ」と思っていました。Python の DB アクセスは ORM（SQLAlchemy 等）か生 SQL かの二択で、この「SQL はそのまま書きたいけど条件組み立ては楽したい」という中間地帯をカバーするものがない。
ということで、Clione-SQL と Doma2 の設計を Python にポーティングしたのが sqlym です。
pip install sqlym
使い方
dataclass を定義して、SQL ファイルを書いて、Sqlym 経由で実行するだけです。
from dataclasses import dataclass
from sqlym import Sqlym
@dataclass
class User:
id: int | None = None
name: str = ""
email: str = ""
conn = sqlite3.connect("example.db")
conn.row_factory = sqlite3.Row
db = Sqlym(conn, sql_dir="sql")
SQL ファイル — DB ツールでそのまま実行できる
-- sql/select_by_name.sql
SELECT id, name, email
FROM users
WHERE 1 = 1
AND name = /* $name */'John'
ORDER BY id
Python から呼ぶ
# 条件あり
users = db.query(User, "select_by_name.sql", {"name": "Alice"})
# 条件なし（name の行が消える）
users = db.query(User, "select_by_name.sql", {"name": None})
INSERT / UPDATE / DELETE も同じ要領です。
db.execute("insert.sql", {"name": "Alice", "email": "alice@example.com"})
user_id = db.insert("insert.sql", {"name": "Bob", "email": "bob@example.com"}) # lastrowid が返る
affected = db.execute("update.sql", {"id": 1, "name": "New Name", "email": "new@example.com"})
affected = db.execute("delete.sql", {"id": 3})
SQLite, PostgreSQL, MySQL, Oracle に対応していて、プレースホルダの形式や LIKE エスケープの違い、Oracle の IN 句 1000 件制限なども吸収します。仕様の詳細は SQL_SYNTAX.ja.md をご覧ください。
リポジトリの examples/ に基本的な CRUD、バッチ処理、トランザクション管理、Clean Architecture での構成例を置いてあるので、気になる方はそちらもどうぞ。
AI コーディングエージェントの時代に思うこと
この sqlym、コーディングの大部分を AI エージェントと一緒に進めました。
自分がやったのは「Clione-SQL のこの仕様を Python で再現したい」という設計意図を伝えることと、出来上がったものを触って「ここ違う」「こうじゃない」とフィードバックすること。いわゆるアーキテクチャとレビューの部分です。
ひと昔前なら、仕事の合間に別言語へのポーティングをやろうなんて思えなかった。Python の DB ドライバごとのプレースホルダの差異を調べて、IN 句の展開処理を書いて、テストを揃えて……正直、モチベーションが続かなかったと思います。
それが今は「こういうものが欲しい」をきちんと言語化できれば、形にできるようになった。AI エージェントは言われたとおりにコードを書くのは得意だけど、「何を作るか」「なぜこの設計なのか」は人間が決める必要がある。その意味で、プログラマの仕事が「コードを書くこと」から「設計と意思決定」にシフトしていくのを実感した経験でもありました。
「作りたいものはあるけど、手を動かす時間がない」という人にとって、今はかなりいい時代だと思います。
おわりに
繰り返しになりますが、sqlym がやっていることの本質は Clione-SQL と Doma2 が確立した設計の Python 移植です。2way SQL という発想、行単位の処理、インデントによる親子関係、パラメータコメント構文——これらはすべて先人の知恵をお借りしています。
Python で「SQL をそのまま書きたいけど動的条件の組み立てが面倒」と感じている方は、ぜひ試してみてください。
フィードバックや Issue お待ちしています。