はじめに
私は普段からバックエンドの開発をしている。その中で、SQLiteやPostgreSQL、時にはScyllaDBなど、さまざまなデータベースを扱ってきた。
そんなある日、ふと疑問に思ったことがある。
「Pythonでクラスの型もフィールド名も定義しているのに、なぜデータベース側でも同じような定義を書く必要があるのだろう?」
もちろん、これには理由があるし、既存のORMなどでも解決できる問題だ。
ただ、私はもっと単純に考えた。
既にPythonに必要な情報があるのなら、それをそのまま利用すればいいのではないか?
そこで作ったのが、Python向けのSQLiteライブラリ「NyanSQLite」だ。
現在はOSSとして公開している。
この記事では、Pythonの型定義とSQLiteのテーブル定義を一つにまとめようと考えた理由、実際にどのような仕組みを作ったのか、開発の途中で揉めた点、そしてその設計が本当に合理的なのかを紹介していく。後半では、使っていて足りないと感じた migrate() を追加した話も書く。
同じ定義を二か所で管理する手間
Pythonでデータを扱うとき、クラスにフィールド名や型を定義することがある。
例えば、ユーザー情報を扱うなら次のようになる。
from pydantic import BaseModel
class User(BaseModel):
id: int
name: str
age: int
一方、SQLiteで同じデータを保存する場合は、テーブル側にも構造を定義する必要がある。
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
age INTEGER NOT NULL
);
一度書くだけなら大した手間ではないと思う。
手間が増えるのは、その後だ。Userにemailというフィールドを追加した場合、Python側のモデルに加えて、SQLite側のテーブルも変更しなければならない。開発を続けていれば、フィールドの追加や型の変更は珍しくない。そのたびに両方の定義を確認する必要があり、変更箇所が増えるほど、修正漏れや食い違いが起きやすくなる。データを保存する際の型の検証も、既にPython側で型を定義しているなら、その情報をそのまま使えるはずだ。
私が解決したかったのは、同じ情報を複数の場所で管理すること、変更のたびに設計を考え直すこと、型の検証を別々に実装することの三つだった。そこで、Pythonのクラス定義をそのままSQLiteのテーブル設計とデータ検証に使う方法を考え、NyanSQLiteの開発を始めた。
作り始めたきっかけ
最初は、ちょっとした発想を試すためのコードだった。型が決まっているのなら、そこからSQLiteのテーブルを推測して自動で作れるのではないか、という発想だ。その確認用のコードをAIに書いてもらったのが始まりになる。
動かしてみると実用的に使えそうだったので、そのまま育てることにした。
開発の進め方も書いておく。設計は自分で考え、複数のAIと議論しながら実装を進めている。コードを書くことはできるが、私はアイデアを出すほうが得意で、全部を自分で書くと効率が悪いので、この分担にしている。
使い方
READMEにあるとおり、Pydanticのモデルをそのままテーブルとして使う。
from pydantic import BaseModel
from nyansqlite import NyanSQLite, Indexed, Searchable
class Article(BaseModel):
id: int # idは自動的に主キーになる
author: Indexed[str] # インデックス付き
title: Searchable[str] # 全文検索(FTS5)の対象
views: int = 0
db = NyanSQLite("blog.db")
db.register(Article) # テーブル作成
db.insert(Article(id=1, author="neko", title="SQLite入門"))
rows = db.query(Article, author="neko", views__gte=0) # Django風のクエリ
hits = db.search(Article, "SQLite") # 全文検索
db.close()
SQLは一行も書かない。insert()やupdate()のときには、Pydanticの検証がそのまま走る。
型からテーブルを作る仕組み
register()は、モデルの型ヒントを読み取ってテーブルを作る。対応は次のとおりだ。
| Pythonの型 | SQLiteの型 |
|---|---|
int、bool
|
INTEGER |
float |
REAL |
str |
TEXT |
bytes |
BLOB |
datetime、date
|
TEXT(ISO形式) |
dict、list
|
TEXT(JSON) |
| 上記以外 | TEXT |
OptionalでないフィールドはNOT NULLになり、idという名前のフィールドは自動で主キーになる。Indexed[T]とSearchable[T]を付ければ、インデックスと全文検索のテーブルも一緒に作られる。
既存のORMを使わなかった理由
自作に踏み切った理由の一つは、既存のORMが私には無駄に複雑に感じられ、パフォーマンスにも不満があったことだ。遅いという声はネット上でも見かける。ただ、当時の計測結果は手元に残っていない。そのため、ここでは数字を出さず、私の感想として書いておく。
揉めたところ:安全性と速度のバランス
開発の中で一番揉めたのは、安全性と速度のバランスだった。
AIと議論していると、安全性をライブラリ側で担保しようとする方向に寄りすぎる場面があった。一方で、速度も追求しすぎて、どこまでやるかの線引きが難しかった。
安全側の例としては、バージョン1.1.5で、register()が既存のテーブルとモデルの違いを検知してSchemaMismatchErrorを出すようになった。条件の指定も、v1.1.4以降は"views > 10"のような単純な比較に絞っている。
速度側では、CHANGELOGに残っているとおり、1.1.5から1.1.7にかけて、フィールドごとのデコーダの事前準備やINSERT文の再利用などを入れた。手元のベンチマーク(Python 3.12)では、WALのデータベースへの10,000件の同期INSERTで、中央値の所要時間がAPSWで30.4%、sqlite3で24.2%短くなった。
この二つを両立させるために、今回は次の整理で判断することにした。読み書きのように毎回通る処理は速さを優先し、テーブルの登録や移行のように、たまにしか通らない処理で安全側に倒す。
止まったあとの手段がなかった
安全側に倒した結果、困ったことがある。モデルにemailを足してregister()を呼ぶと、こうなる。
class User(BaseModel):
id: int
name: str
age: int
email: str = ""
db = NyanSQLite("t.db")
db.register(User)
SchemaMismatchError: Existing table 'user' differs from model User:
missing columns=['email'], extra columns=[], incompatible columns=[].
Migrate the table before register().
既存のテーブルは勝手に書き換えない。データを守る判断としては筋が通っている。ただ、メッセージには「Migrate the table before register()」とあるのに、その移行をする手段がライブラリの中になかった。自分でALTER TABLEを書くことになり、それでは「同じ定義を二か所で書かない」という出発点に戻ってしまう。
migrate() を試作した
移行の機能は以前から欲しかったが、どこまで自動でやるのかという設計に悩んでいて、手を付けられずにいた。今回、plan_migration()とmigrate()を試作した。実装はClaudeに任せ、方針は次の三点にした。
-
まず計画を見る。
plan_migration()はDBを変更せず、何が実行されるかを返す。 - データを失わない変更は、そのまま実行する。 カラムの追加がこれにあたる。
-
データが変わる可能性のある変更は、明示的に許可する。 カラムの削除、型の変更、NULL許可からNOT NULLへの変更が対象で、
allow_destructive=Trueが必要になる。
実際に動かすと、こうなる。
print(db.plan_migration(User))
user:
- add column email (TEXT)
- add column nick (TEXT)
db.migrate(User) # 追加だけなのでそのまま実行できる
db.register(User) # 既存の行には既定値が入る
[User(id=1, name='a', age=3, email='', nick=None),
User(id=2, name='b', age=4, email='x@y', nick=None)]
型を変えたり、カラムを削除したりする場合は、許可なしでは止まる。
class User(BaseModel):
id: int
name: str
age: str # int から str へ。email と nick は削除
db.migrate(User)
MigrationError: This migration can change or discard existing data. Review it with
plan_migration() and pass allow_destructive=True to apply it:
user:
- rebuild table user (drop columns email, nick; change age: INTEGER -> TEXT); 2 row(s) copied [destructive]
allow_destructive=Trueを付けると、テーブルを作り直して行をコピーする。コピーの後に、値が新しい型に収まっているかを確認し、問題がなければ入れ替える。例えば文字列"abc"を整数のカラムに移そうとすると、SQLiteは何も言わずに文字列のまま保存してしまうので、この確認でMigrationErrorにしている。すべての処理は一つのトランザクションで動き、失敗すれば元に戻る。
必須のフィールドを既定値なしで追加する場合は、既存の行に入れる値がないので、実行できないようにしてある。既定値を付けるか、Optionalにする必要がある。
速度は、手元(Python 3.13、APSW)で20万行のテーブルに対して、カラム追加が2.3ms、型変更を伴う作り直しが116msだった。登録や移行はたまにしか通らない処理なので、この程度なら問題ないと考えている。
推測できない部分は自分で書く
試作してみて、型から読み取れない変更が思った以上に多いと気づいた。代表はカラム名の変更だ。型は同じで名前だけが変わると、ライブラリからは「古いカラムを削除して、新しいカラムを追加した」ようにしか見えず、中身が引き継がれない。必須のカラムを足す場合も、既存の行に何を入れるかは型からは決まらない。
そこで、こうした部分は利用者が明示する形にした。
class User(BaseModel):
__nyan_renames__ = {"email": "email_address"} # 新しい名前: 古い名前
id: int
name: str
email: str
tier: str # 新しい必須カラム
fill = {"tier": lambda row: "pro" if row["name"] == "neko" else "free"}
print(db.migrate(User, dry_run=True, fill=fill))
user:
- rename column email_address -> email
- rebuild table user (add column tier; fill tier in Python); 2 row(s) copied
plan = db.migrate(User, fill=fill, backup=True)
db.register(User)
id=1 name='neko' email='neko@example.com' tier='pro'
id=2 name='inu' email='inu@example.com' tier='free'
fillには値そのものか、既存の行を受け取る関数を渡せる。改名の指定もfillも、すでに移行したカラムには何も起こさない。そのため、起動時のコードに残したままでも、2回目以降は「no changes」になって通る。
fillが返した値も、新しい型に収まっているかを確認する。収まらなければMigrationErrorになり、途中までの変更は元に戻る。
自動で移行する選択肢とバックアップ
毎回migrate()を呼ぶのは面倒なので、登録のときにまとめて行うオプションも用意した。
db.register(User) # 既定: 食い違えば SchemaMismatchError で止まる
db.register(User, on_mismatch="migrate") # 安全な変更だけ自動で実行
既定は今までどおり止まる側にして、自動はオプトインにしている。自動のときでも、カラムの削除や型の変更のようにデータが変わる可能性のある変更には、allow_destructive=Trueが別に必要だ。AIとの議論で安全に寄りすぎた経験があるので、勝手に進める範囲は小さく、進めたいときは自分で選ぶ形に落ち着いた。
バックアップはbackup=Trueで取れる。SQLiteのVACUUM INTOで、変更の前にデータベースをコピーする。既定では取らない。大きなデータベースではコピーに時間がかかるし、使うかどうかは利用者が選べばよいと考えたからだ。
本当に合理的か
最初の問いに戻る。型の情報から全部を推測する設計は、合理的だったのか。
小さな範囲では合理的だったと思う。モデルを一か所に書くだけで、テーブルの作成、型の検証、インデックス、全文検索までそろう。SQLを書く場面がほとんどなくなり、個人開発やスクリプトのような用途では、かなり楽になる。
一方で、型から推測できるのは「今のモデルがこうである」ことまでで、「過去のテーブルからどう変わったか」は型だけでは分からない。変更を勝手に反映すればデータを壊す危険があり、止めれば手段が必要になる。二重管理は減ったが、移行の手順という別の管理が生まれた。migrate()はそこを埋めるための試作で、設計はまだ詰めている途中だ。
想定している用途は、個人開発や小規模なアプリ、Botやスクリプト、APIサーバー、そして試作段階のプロトタイプである。JOINのような複雑なクエリ用のAPIは用意していないので、必要になったときはexecute_raw()で生のSQLを流してもらう形にしている。型の情報から自動で処理できる範囲を広く取り、そこから外れる部分は無理に抱え込まない、という割り切りだ。
対応するデータベースはSQLiteだけである。PostgreSQLなどへの対応は今のところ考えていない。希望があれば検討するつもりだが、サーバー型のデータベースでは既存のツールが充実しているので、SQLiteほどの価値は出にくいと思っている。
おわりに
NyanSQLiteは、「型を書いたなら、それをデータベースにも使えばいい」という発想から作ったライブラリだ。作ってみて、安全と速度のバランス、そして変更に追従する仕組みが、型を一つにまとめたあとの本当の課題だと分かった。
pip install nyansqliteで試せる。使ってみての感想や、うまく動かなかったところがあれば、IssueやXで教えてもらえるとありがたい。
(公式ドキュメント: https://nyansqlite.disnana.com/ )
※ 本記事のmigrate()は、現時点ではリポジトリに取り込む前の試作で、仕様は変わる可能性があります。
