Pythonのsqlite3入門|SQLiteの操作方法とプレースホルダ・エラー対処
Python には、データベース「SQLite」を操作する sqlite3 モジュールが標準で入っています。サーバーを用意する必要がなく、インストールもいらないので、ToDo アプリのデータ保存や、CSV を集計するちょっとしたスクリプトにすぐ使えます。
この記事では、Windows 11 の Python 3.12(SQLite 3.45.3)で実際に動かした結果つきで、次のことを解説します。SQL の文法そのものは「SQL入門:SELECT文の基本」などの記事に任せ、ここでは Python から使うときの書き方に絞ります。
- connect・execute・commit・close の基本と、プレースホルダ(
?と:name) - fetchone・fetchall と、列名で値を取り出す
sqlite3.Row - 型の対応と、Python 3.12 で非推奨になった日付の扱い
- CSV の家計簿を集計する実例と、よくあるエラーの直し方
基本の流れ:connect → execute → commit → close
SQLite は、データベース全体が 1 つのファイルに入る小さなデータベースです。まずは ToDo を 2 件保存して読み出してみます。
import sqlite3
con = sqlite3.connect("todo.db")
cur = con.cursor()
cur.execute("CREATE TABLE IF NOT EXISTS todo ("
"id INTEGER PRIMARY KEY, title TEXT NOT NULL,"
" done INTEGER NOT NULL DEFAULT 0)")
cur.execute("INSERT INTO todo (title) VALUES (?)", ("牛乳を買う",))
cur.execute("INSERT INTO todo (title, done) VALUES (:title, :done)",
{"title": "記事を書く", "done": 1})
con.commit()
print(cur.lastrowid)
cur.execute("SELECT id, title, done FROM todo")
print(cur.fetchall())
con.close()
todo.py という名前で保存し、py todo.py で実行すると次のように表示されました。同じフォルダーに todo.db(8,192 バイト)ができています。
2
[(1, '牛乳を買う', 0), (2, '記事を書く', 1)]
もう一度実行すると 4 と 4 件が表示されます。データがファイルに残っているからです。それぞれの役割は次のとおりです。
- sqlite3.connect(ファイル名):データベースにつなぎ、接続(Connection)を返します。ファイルがなければ新しく作ります。
":memory:"を渡すと、ファイルを作らずメモリ上だけのデータベースになり、閉じると消えます(試し書きやテストに便利です) - カーソル(Cursor):SQL を実行し、結果を 1 行ずつ取り出すための窓口です。
con.execute()と書くと、カーソルを作って execute し、そのカーソルを返してくれます(以降はこの短い書き方を使います) - commit():INSERT などの変更を確定します。呼ばずに閉じると変更は取り消されます
- lastrowid:最後に execute で INSERT した行の id です
値はプレースホルダで渡す(? と :name)
上の例で SQL の中に書いた ? や :title をプレースホルダ(値を入れる場所の目印)と呼びます。値は SQL の文字列に埋め込まず、execute の 2 つ目の引数で渡します。
? にはタプルなどで ? と同じ数の値を渡します。値が 1 つでも ("牛乳を買う",) のようにカンマが必要です。:name には辞書を渡します。項目が多いときは、どの値がどこに入るか分かりやすくなります。
f 文字列や + で SQL を組み立てると、入力された値に ' が入っただけで SQL の意味が変わり、他人のデータを読まれたり消されたりする「SQL インジェクション」の原因になります。公式ドキュメントも、文字列の操作で SQL を組み立てず、必ずプレースホルダを使うように書いています。仕組みは「SQLインジェクションとは?仕組みとプレースホルダによる対策」で実演しています。
なお、プレースホルダで渡せるのは「値」だけです。テーブル名・列名・ASC/DESC は ? にできないので、プログラムで用意した候補から選ぶようにします。
executemany でまとめて追加する
同じ INSERT を何件も実行するときは executemany() に「値の並びのリスト」を渡します。ここからはメモリ上のデータベースで試します。
import sqlite3
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE todo (id INTEGER PRIMARY KEY, title TEXT, done INTEGER)")
rows = [("牛乳を買う", 0), ("記事を書く", 1), ("部屋の掃除", 0)]
cur = con.executemany("INSERT INTO todo (title, done) VALUES (?, ?)", rows)
print(cur.rowcount)
表示は 3 で、rowcount から追加された行数が分かります。辞書のリストを渡せば :name 形式も使えます(後の家計簿の例で使います)。executemany に書ける SQL は INSERT・UPDATE などの 1 文だけで、SELECT の結果は捨てられます。
結果を取り出す:fetchone・fetchall・for 文
SELECT の結果は、カーソルから取り出します。先ほどの続きで実行します。
cur = con.execute("SELECT * FROM todo ORDER BY id")
print(cur.fetchone())
print(cur.fetchone())
print(cur.fetchall())
print(cur.fetchone())
for row in con.execute("SELECT id, title FROM todo WHERE done = ?", (0,)):
print(row)
(1, '牛乳を買う', 0)
(2, '記事を書く', 1)
[(3, '部屋の掃除', 0)]
None
(1, '牛乳を買う')
(3, '部屋の掃除')
fetchone() は次の 1 行をタプルで返し、もう行がなければ None です。「id で 1 件探す」ときは None かどうかで見つかったかを判定できます。fetchall() は残りの行(取り出し済みの行は除く)をリストで返します。for row in カーソル は 1 行ずつ処理するので、行数が多いときもメモリを節約できます。
row_factory = sqlite3.Row で列名を使う
タプルの row[1] は、SELECT の列の順番を変えると別の値を指してしまいます。接続の row_factory に sqlite3.Row を設定すると、row["title"] のように列名で取り出せます。
con.row_factory = sqlite3.Row
row = con.execute("SELECT id, title, done FROM todo WHERE id = ?", (2,)).fetchone()
print(row["title"], row["TITLE"], row[0], row.keys())
print(dict(row))
記事を書く 記事を書く 2 ['id', 'title', 'done']
{'id': 2, 'title': '記事を書く', 'done': 1}
列名の大文字・小文字は区別されず、番号でも取り出せます。dict(row) で辞書にすれば、JSON にして返すのも簡単です。COUNT(*) などの計算した列は、SQL で AS total のように別名を付けておくと row["total"] で取り出せます。
commit と with 文、接続の閉じ方
最初の例で con.commit() を消して実行すると、次に接続したとき INSERT した行は 0 件でした。公式ドキュメントにも、確定していない変更があるまま閉じると暗黙に取り消す(ロールバックする)と書かれています。
接続を with で使うと、ブロックが正常に終われば commit、例外が起きれば rollback してくれます。ただし、with を抜けても接続は閉じません。閉じるところまで任せたいときは contextlib.closing() を組み合わせます。
import sqlite3
from contextlib import closing
with sqlite3.connect("memo.db") as con:
con.execute("CREATE TABLE IF NOT EXISTS memo (body TEXT)")
con.execute("INSERT INTO memo VALUES (?)", ("with で commit",))
print(con.execute("SELECT count(*) FROM memo").fetchone()) # まだ使える
con.close()
with closing(sqlite3.connect("memo.db")) as con:
with con:
con.execute("INSERT INTO memo VALUES (?)", ("closing で閉じる",))
try:
con.execute("SELECT 1")
except sqlite3.ProgrammingError as e:
print(e)
(1,)
Cannot operate on a closed database.
1 つ目の with の後でも SELECT できた(=閉じていない)のに対し、closing の後は「閉じたデータベースは操作できない」というエラーになりました。外側の closing が閉じる係、内側の with con: が commit・rollback の係です。Python 3.13 からは、close() せずに接続が消えると ResourceWarning(後片付け忘れの警告)が出るようになったので、閉じる習慣を付けておきましょう。
トランザクション(変更をまとめて確定・取り消す仕組み)や、3.12 で追加された autocommit 引数については「SQLのINSERT・UPDATE・DELETEとトランザクション入門」で、注文処理を例に詳しく解説しています。
Python と SQLite の型の対応
そのまま渡せる型と、取り出したときの型は次のとおりです(公式ドキュメントの表を、SQLite の typeof() で確かめました)。
| Python の型 | SQLite の型 | 取り出したとき |
|---|---|---|
| None | NULL | None |
| int | INTEGER | int |
| float | REAL | float |
| str | TEXT | str |
| bytes | BLOB | bytes |
注意したい点が 2 つあります。True は int の仲間なので 1 として保存され、取り出すと 1 です。また、INTEGER の列に文字列 "123" を入れると SQLite が数値の 123 に変えて保存しました(列の型が厳密ではないのが SQLite の特徴です)。リストなど表にない型を渡すと ProgrammingError: Error binding parameter 1: type 'list' is not supported になります。リストや辞書を保存したいときは、JSON の文字列にしてから渡します。
日付の扱い(3.12 で既定のアダプターが非推奨に)
SQLite には日付専用の型がありません。これまで sqlite3 は datetime.date などを自動で文字列に変える「既定のアダプター」を持っていましたが、Python 3.12 で非推奨になりました(What’s New in Python 3.12 と sqlite3 の公式ドキュメントで確認)。3.12 で date と datetime をそのまま渡すと、保存はされますが次の警告が出ます。
DeprecationWarning: The default date adapter is deprecated as of Python 3.12; see the sqlite3 documentation for suggested replacement recipes
公式ドキュメントは、代わりに「アダプターとコンバーターのレシピ」を参考に自分で登録するよう案内しています。いちばん簡単なのは、ISO 8601 形式(2026-10-19)の文字列で保存する方法です。
import datetime
import sqlite3
sqlite3.register_adapter(datetime.date, lambda d: d.isoformat())
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE expense (day TEXT, amount INTEGER)")
con.execute("INSERT INTO expense VALUES (?, ?)", (datetime.date(2026, 10, 19), 480))
day, amount = con.execute("SELECT day, amount FROM expense").fetchone()
print(repr(day))
print(datetime.date.fromisoformat(day))
con.close()
'2026-10-19'
2026-10-19
警告は出なくなりました。取り出すと文字列なので、必要なら date.fromisoformat() で戻します。自動で date に戻したいときは、sqlite3.register_converter("date", ...) でコンバーターを登録し、connect(..., detect_types=sqlite3.PARSE_DECLTYPES) で接続して列の型を DATE と宣言します(試したところ datetime.date(2026, 10, 19) が返りました)。日時はタイムゾーンを含めるかどうかも決めておきましょう(「Pythonのdatetime」の記事も参考になります)。
実例:CSV の家計簿を読み込んで集計する
ここまでの内容をまとめて、家計簿の CSV をデータベースに入れ、月ごと・費目ごとに集計します。CSV(UTF-8)は次の内容で kakeibo.csv として保存します。
日付,費目,内容,金額
2026-09-03,食費,スーパー,2480
2026-09-10,交通費,ICカードチャージ,3000
2026-09-18,食費,ランチ,980
2026-10-01,日用品,洗剤,598
2026-10-05,食費,スーパー,3120
2026-10-12,交通費,ICカードチャージ,2000
2026-10-15,食費,カフェ,450
同じフォルダーに kakeibo.py を作ります。
import csv
import sqlite3
from contextlib import closing
from pathlib import Path
BASE = Path(__file__).parent
with open(BASE / "kakeibo.csv", encoding="utf-8", newline="") as f:
rows = [{"day": r["日付"], "cat": r["費目"], "amount": int(r["金額"])}
for r in csv.DictReader(f)]
with closing(sqlite3.connect(BASE / "kakeibo.db")) as con:
con.row_factory = sqlite3.Row
con.execute("CREATE TABLE IF NOT EXISTS expense (day TEXT NOT NULL,"
" cat TEXT NOT NULL, amount INTEGER NOT NULL)")
with con: # 全部入ったら commit、途中で失敗したら rollback
con.execute("DELETE FROM expense")
con.executemany("INSERT INTO expense VALUES (:day, :cat, :amount)", rows)
print(f"{len(rows)} 件を読み込みました")
print("■ 月ごとの合計")
sql = ("SELECT substr(day, 1, 7) AS month, sum(amount) AS total"
" FROM expense GROUP BY month ORDER BY month")
for row in con.execute(sql):
print(f"{row['month']}:{row['total']:,} 円")
month = "2026-10"
print(f"■ {month} の費目別")
sql = ("SELECT cat, count(*) AS n, sum(amount) AS total FROM expense"
" WHERE substr(day, 1, 7) = ? GROUP BY cat ORDER BY total DESC")
for row in con.execute(sql, (month,)):
print(f"{row['cat']}:{row['n']} 件 {row['total']:,} 円")
py kakeibo.py
7 件を読み込みました
■ 月ごとの合計
2026-09:6,460 円
2026-10:6,168 円
■ 2026-10 の費目別
食費:2 件 3,570 円
交通費:1 件 2,000 円
日用品:1 件 598 円
CSV の値はすべて文字列なので、金額は int() で数値にしてから入れます(CSV の読み方は「PythonでCSVを読み書きする方法」で解説しています)。DELETE と executemany を 1 つの with con: に入れたので、途中で失敗しても「古いデータだけ消えた」状態にならず、何度実行しても 7 件のままです。ファイルの場所は Path(__file__).parent 基準にしました(理由は次の章で説明します)。
集計の SQL が長くなったら、SQL整形ツールで改行・インデントを入れると読みやすくなります。
よくあるエラーと直し方
実際に起こしたエラーのメッセージと、主な原因をまとめます。sqlite3 のエラーはどれも sqlite3.Error の仲間なので、except sqlite3.Error でまとめて受け取れます(例外の基本は「Pythonの例外処理入門」を参照)。
| エラー | 主な原因 |
|---|---|
| OperationalError: no such table: todos | テーブル名の書き間違い、または別のファイルにつないでいる |
| OperationalError: database is locked | 別の接続が書き込み中のまま commit していない |
| ProgrammingError: Incorrect number of bindings supplied. The current statement uses 1, and there are 5 supplied. | 値 1 つを ("牛乳を買う",) ではなく文字列のまま渡した(5 文字が 5 個の値と見なされた) |
| ProgrammingError: You did not supply a value for binding parameter :id. | 辞書に :name と同じ名前のキーがない |
| ProgrammingError: … uses 0, and there are 1 supplied. | '?' と ? を引用符で囲んだ(ただの文字になる) |
| ProgrammingError: You can only execute one statement at a time. | ; で区切った複数の SQL を渡した |
| ProgrammingError: Cannot operate on a closed database. | close() した後の接続を使った |
no such table:別のフォルダーに空のファイルができている
テーブル名が正しいのにこのエラーが出るときは、ファイルの場所を疑います。connect("kakeibo.db") の相対パスは、スクリプトの場所ではなく実行したときのカレントフォルダーが基準です。しかも connect はファイルがないと黙って新しく作ります。試しに、家計簿のフォルダーの 1 つ上から py kakeibo\report.py(connect("kakeibo.db") で件数を数えるだけのスクリプト)を実行すると、1 つ上のフォルダーに空の kakeibo.db ができて no such table: expense になりました。
対策は、実例のように Path(__file__).parent を基準にすることです。ファイルがないときに作らずエラーにしたい場合は、sqlite3.connect("file:kakeibo.db?mode=rw", uri=True) と書くと unable to open database file で止まります。パスの扱いは「Pythonのpathlib」の記事も参考にしてください。
database is locked:commit していない接続がある
SQLite は、同時に書き込めるのが 1 つの接続だけです。接続 a で INSERT して commit しないまま、接続 b(timeout=1)で INSERT すると、約 1 秒待ってから database is locked になりました。a が commit した後は、b の INSERT も成功しました。
変更したらすぐ commit する(with を使うと忘れにくい)、同じファイルへの接続をいくつも開かない、DB を開いたままのツールや止まっていないスクリプトがないか確かめる、の 3 つで多くは直ります。待ち時間は connect() の timeout(秒、既定は 5 秒)で延ばせますが、原因を直すのが先です。
よくある質問
Q. データベースの中身を手軽に見るには?
Python 3.12 からは、sqlite3 モジュールにコマンドラインの機能が付きました。ファイル名と SQL を渡すと結果が表示されます。
py -m sqlite3 kakeibo.db "SELECT cat, sum(amount) FROM expense GROUP BY cat"
('交通費', 5000)
('日用品', 598)
('食費', 7030)
SQL を付けずに py -m sqlite3 kakeibo.db とすると、SQL を対話的に入力できます。なお、この PC(Windows 11)には SQLite 本家の sqlite3 コマンドは入っていませんでした。
まとめ
sqlite3 は connect → execute → commit → close が基本です。値は必ず ? か :name のプレースホルダで渡し、sqlite3.Row で列名を使うと読みやすくなります。with は commit・rollback の係で、閉じるのは close() か closing() です。日付は 3.12 から自分でアダプターを登録します。
関連する記事・ツール
- SQL整形ツール
- SQL入門:SELECT文の基本|WHERE・ORDER BY・LIMITの使い方と注意点
- SQLのINSERT・UPDATE・DELETEとトランザクション入門|実行結果で解説
- SQLインジェクションとは?仕組みとプレースホルダによる対策を実行結果で解説
- PythonでCSVを読み書きする方法|csvモジュールとExcelの文字化け・空行対策
- Pythonの例外処理入門|try・except・finally・raiseの使い方