sqlite3
--- SQLite データベース用の DB-API 2.0 インターフェース¶
ソースコード: Lib/sqlite3/
SQLite は、軽量なディスク上のデータベースを提供する C ライブラリです。別のサーバプロセスを用意する必要なく、 SQL クエリー言語の非標準的な一種を使用してデータベースにアクセスできます。一部のアプリケーションは内部データ保存に SQLite を使えます。また、SQLite を使ってアプリケーションのプロトタイプを作り、その後そのコードを PostgreSQL や Oracle のような大規模データベースに移植するということも可能です。
The sqlite3
module was written by Gerhard Häring. It provides an SQL interface
compliant with the DB-API 2.0 specification described by PEP 249, and
requires SQLite 3.15.2 or newer.
この文書には大きく分けて 4 つの節があります:
チュートリアル
sqlite3
モジュールの使い方を学びます。リファレンス このモジュールが定義するクラスと関数について説明します。
ハウツー・ガイド 特定のタスクの処理方法について詳しく説明します。
説明 トランザクション制御の背景をより深く掘り下げて説明します。
参考
- https://www.sqlite.org
SQLite のウェブページ。ここの文書ではサポートされる SQL 方言の文法と使えるデータ型を説明しています。
- https://www.w3schools.com/sql/
SQL 学習に効くチュートリアル、リファレンス、実例集。
- PEP 249 - Database API Specification 2.0
Marc-Andre Lemburg により書かれた PEP。
チュートリアル¶
このチュートリアルでは、あなたは基本的な sqlite3
機能を使用して、 例としてモンティ・パイソンの映画のデータベースを作成します。 あなたがカーソル(cursors)やトランザクション(transactions)を含むデータベースの基本概念を理解していることを前提としています。
最初に、新しいデータベースを作成し、データベース接続(connection)を開いて sqlite3
が動作できるようにする必要があります。 sqlite3.connect()
を呼び出して、データベース tutorial.db
への接続を現在の作業ディレクトリに作成します。存在しない場合は暗黙的に作成します。
import sqlite3
con = sqlite3.connect("tutorial.db")
返された Connection
オブジェクト con
は、ディスク上のデータベースへの接続を表します。
SQL 文を実行し、SQL クエリから結果を取得するには、データベース・カーソルを使用する必要があります。 con.cursor()
を呼び出して Cursor
を作成してください:
cur = con.cursor()
さて、今やデータベース接続とカーソルを取得したので、タイトル(title)とリリース年(year)と、レビュー・スコア(score)の列(columns)を持つデータベース・テーブル movie
を作成できます。 簡単にするために、テーブル宣言では列名だけを使用できます。SQLite の 柔軟な型付け(flexible typing)機能のおかげで、データ型の指定はオプションになっています。 cur.execute(...)
を呼び出して CREATE TABLE
文を実行してください:
cur.execute("CREATE TABLE movie(title, year, score)")
SQLite に組み込みの sqlite_master
テーブルに対してクエリを実行することで、新しいテーブルが作成されたことを確認できます。このテーブルには、 movie
テーブル定義のエントリが含まれているはずです(詳細は The Schema Table 参照)。 cur.execute(...)
を呼び出してクエリを実行して、その結果を res
に代入し、結果の行(row)を取得するために res.fetchone()
を呼び出します:
>>> res = cur.execute("SELECT name FROM sqlite_master")
>>> res.fetchone()
('movie',)
We can see that the table has been created,
as the query returns a tuple
containing the table's name.
If we query sqlite_master
for a non-existent table spam
,
res.fetchone()
will return None
:
>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() is None
True
ここで、 INSERT 文を実行して SQL のリテラルとして提供された 2 行のデータを追加し、 再度 cur.execute(...)
を呼び出して追加します:
cur.execute("""
INSERT INTO movie VALUES
('Monty Python and the Holy Grail', 1975, 8.2),
('And Now for Something Completely Different', 1971, 7.5)
""")
INSERT
文は、変更がデータベースに保存される前にコミットする必要がある、トランザクションを暗黙的に開きます(詳細は、 トランザクション制御 参照)。 トランザクションをコミットするために接続オブジェクト(connection object)の con.commit()
を呼び出して下さい:
con.commit()
SELECT
クエリを実行することで、データが正しく挿入されたことを確認できます。 結果のすべての行を返すには、おなじみの cur.execute(...)
を使用して結果を res
に代入し、 res.fetchall()
を呼び出して下さい:
>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]
結果は、2 つの タプル
の リスト
で、 それぞれのタプルにその行の score
値が含まれています。
ここで、 cur.executemany(...)
を呼び出して、さらに 3 行挿入します:
data = [
("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
("Monty Python's The Meaning of Life", 1983, 7.5),
("Monty Python's Life of Brian", 1979, 8.0),
]
cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
con.commit() # Remember to commit the transaction after executing INSERT.
data
をクエリに結び付け(bind)するために ?
プレースホルダが使用されていることに注意してください。 SQL インジェクション攻撃(SQL injection attacks)を避けるために、Python の値を SQL 文に結び付けするには、常に 文字列フォーマット の代わりにプレースホルダを使用してください(詳細は プレースホルダを使用して SQL クエリに値を結び付ける方法 参照)。
SELECT
クエリを実行することで、新しい行が挿入されたことを確認できます。今回は、クエリの結果を反復処理します:
>>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
... print(row)
(1971, 'And Now for Something Completely Different')
(1975, 'Monty Python and the Holy Grail')
(1979, "Monty Python's Life of Brian")
(1982, 'Monty Python Live at the Hollywood Bowl')
(1983, "Monty Python's The Meaning of Life")
各行(row)は タプル
の (year, title)
の 2 つの項目であり、クエリで選択された列(columns)にマッチします。
最後に、 con.close()
を呼び出して既存の接続(connection)を閉じ、新しい接続を開き、新しいカーソルを作成してから、データベースに対してクエリを実行して、データベースがディスクに書き込まれたことを確認します:
>>> con.close()
>>> new_con = sqlite3.connect("tutorial.db")
>>> new_cur = new_con.cursor()
>>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
>>> title, year = res.fetchone()
>>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
>>> new_con.close()
これで、あなたは、 sqlite3
モジュールを使用して SQLite データベースを作成し、複数の方法でデータを挿入し、そこから値を取得することができるようになりました。
参考
ハウツー・ガイド も参考にしてください:
トランザクション制御 トランザクション制御の背景についてより深く掘り下げた説明。
リファレンス¶
モジュール関数¶
- sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)¶
SQLite データベースとの接続(connection)を開きます。
- パラメータ:
database (path-like object) -- The path to the database file to be opened. You can pass
":memory:"
to create an SQLite database existing only in memory, and open a connection to it.timeout (float) -- テーブルがロックされている場合、
OperationalError
を送出する前に接続を待機する秒数。 別の接続がテーブルを変更するためにトランザクションを開くと、そのテーブルはトランザクションがコミットされるまでロックされます。 デフォルトは 5 秒です。detect_types (int) --
register_converter()
で登録された変換関数を使用して、 SQLite でネイティブにサポートされている型 以外のデータ型を検出して、 Python 型に変換するかどうか、そして、その変換方法を制御します。 これは、PARSE_DECLTYPES
とPARSE_COLNAMES
を(ビット論理和|
を使用して)任意の組み合わせで設定することで有効になります。 両方のフラグが設定されている場合、宣言された型よりも列名が優先されます。 detect_types パラメータが設定されている場合でも、 生成されたフィールド(たとえばmax(data)
)の型は検出できず、代わりにstr
が返されます。デフォルト (0
) では、データ型検出は無効になっています。isolation_level (str | None) -- Control legacy transaction handling behaviour. See
Connection.isolation_level
and isolation_level 属性に依るトランザクション制御 for more information. Can be"DEFERRED"
(default),"EXCLUSIVE"
or"IMMEDIATE"
; orNone
to disable opening transactions implicitly. Has no effect unlessConnection.autocommit
is set toLEGACY_TRANSACTION_CONTROL
(the default).check_same_thread (bool) --
True
(これがデフォルトです)なら、データベース接続を作成したスレッド以外のスレッドがデータベース接続を使用すると、ProgrammingError
が送出されます。False
なら、接続は複数のスレッドからアクセスできます。ただし、データの破損を避けるために、ユーザーによる書き込み操作の直列化が必要になることがあります。詳細はthreadsafety
を参照してください。factory (Connection) -- デフォルトの
Connection
クラスでない場合に接続(connection)を作成するConnection
のカスタム・サブクラスです。cached_statements (int) --
sqlite3
がこの接続(connection)のために内部的にキャッシュするSQL文(statements)の数で、 パース時のオーバーヘッドを回避します。 デフォルトでは、128 文(statements)です。uri (bool) --
True
に設定すると、 database は、ファイル・パス(path)とオプションのクエリ文字列を含む URI として解釈されます。 スキームの部分は"file:"
でなければならず、パス(path)は相対パスまたは絶対パスにすることができます。 クエリ文字列により、 パラメーターを SQLite に渡すことができ、さまざまな SQLite URI の操作方法 が有効になります。autocommit (bool) -- Control PEP 249 transaction handling behaviour. See
Connection.autocommit
and autocommit 属性に依るトランザクション制御 for more information. autocommit currently defaults toLEGACY_TRANSACTION_CONTROL
. The default will change toFalse
in a future Python release.
- 戻り値の型:
引数
database
を指定して 監査イベントsqlite3.connect
を送出します。引数
connection_handle
を指定して 監査イベントsqlite3.connect/handle
を送出します。バージョン 3.4 で変更:
uri
パラメータが追加されました。バージョン 3.7 で変更: database は、文字列だけでなく、 path-like object にすることもできるようになりました。
バージョン 3.10 で変更: Added the
sqlite3.connect/handle
auditing event.バージョン 3.12 で変更: Added the autocommit parameter.
バージョン 3.13 で変更: Positional use of the parameters timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, and uri is deprecated. They will become keyword-only parameters in Python 3.15.
- sqlite3.complete_statement(statement)¶
文字列 statement が 1 つ以上の完全な SQL 文を含んでいるように見える場合、
True
を返します。 閉じられていない文字列リテラルがないことと、文がセミコロンで終了していることを確認する以外の、構文の検証やパースは行われません。例えば:
>>> sqlite3.complete_statement("SELECT foo FROM bar;") True >>> sqlite3.complete_statement("SELECT foo") False
この関数は、コマンドライン入力時に便利で、入力されたテキストが完全な SQL 文を形成しているように見えるかどうか、または
execute()
を呼び出す前に追加の入力が必要かどうかを判断するのに使えます。実際の使用例については、 Lib/sqlite3/__main__.py の
runsource()
を参照してください。
- sqlite3.enable_callback_tracebacks(flag, /)¶
コールバックのトレースバックを有効または無効にします。 デフォルトでは、ユーザー定義関数や集計関数や変換関数や authorizer コールバックなどではトレースバックを取得しません。それらをデバッグしたい場合は、 flag を
True
に設定してこの関数を呼び出し。その後、sys.stderr
のコールバックからトレースバックを取得します。 機能を再び無効にするにはFalse
を使用します。注釈
Errors in user-defined function callbacks are logged as unraisable exceptions. Use an
unraisable hook handler
for introspection of the failed callback.
- sqlite3.register_adapter(type, adapter, /)¶
adapter 呼び出し可能オブジェクト を登録して、 Python 型の type を SQLite の型に適合させます。適合関数(adapter)アダプターは、 Python 型 type の Python オブジェクトを唯一の引数として使用して呼び出され、 SQLite がネイティブに理解する型 の値を返す必要があります。
- sqlite3.register_converter(typename, converter, /)¶
converter 呼び出し可能オブジェクト を登録して、 typename 型の SQLite オブジェクトを指定の型の Python オブジェクトに変換します。変換関数(converter)、 typename 型のすべての SQLite 値に対して呼び出されます。 変換関数には
bytes
オブジェクトが渡され、目的の Python 型のオブジェクトを返す必要があります。型検出の仕組みについては、connect()
のパラメーター detect_types を参照してください。注釈: typename とクエリ内の型の名前は、大文字小文字を区別せずにマッチングされます。
モジュール定数¶
- sqlite3.LEGACY_TRANSACTION_CONTROL¶
古いスタイル (Python 3.12 より前) のトランザクション制御の振る舞いを選択するには、
autocommit
に、この定数を設定します。詳細については isolation_level 属性に依るトランザクション制御 を参照してください。
- sqlite3.PARSE_COLNAMES¶
このフラグ値を
connect()
の detect_types パラメーターに渡し、クエリの列(column)名からパースされた型名を変換関数辞書(converter dictionary)のキーとして使用して変換関数を探します。型名は角括弧([]
)で囲む必要があります。SELECT p as "p [point]" FROM test; ! will look up converter "point"
このフラグは
|
(ビット論理和)演算子を使用してPARSE_DECLTYPES
と組み合わせることができます。
- sqlite3.PARSE_DECLTYPES¶
このフラグ値を
connect()
の detect_types パラメーターに渡して、各列(column)で宣言した型を使用して変換関数を探します。型は、データベース・テーブルの作成時に宣言します。sqlite3
は、宣言された型の、最初の単語を、変換関数辞書(converter dictionary)のキーとして使用して、変換関数を探します。例えば:CREATE TABLE test( i integer primary key, ! will look up a converter named "integer" p point, ! will look up a converter named "point" n number(10) ! will look up a converter named "number" )
このフラグは
|
(ビット論理和)演算子を使用してPARSE_COLNAMES
と組み合わせることができます。
- sqlite3.SQLITE_OK¶
- sqlite3.SQLITE_DENY¶
- sqlite3.SQLITE_IGNORE¶
Connection.set_authorizer()
に渡す 呼び出し可能オブジェクト が返す必要のあるフラグ。これらは以下の意味です:アクセスは許可されました(
SQLITE_OK
)当該SQL文全体の実行をエラーで中止(abort)する必要があります(
SQLITE_DENY
)列(column)は
NULL
値として扱う必要がありますが、当該SQL文の実行は続行する必要があります(SQLITE_IGNORE
)
- sqlite3.apilevel¶
サポートされている DB-API レベルを示す文字列定数。 DB-API で必要です。
"2.0"
とハードコーディングされています。
- sqlite3.paramstyle¶
sqlite3
モジュールが期待するパラメータ・マーカーのフォーマットの種類をあらわす文字列定数です。 DB-API で必要です。"qmark"
とハードコーディングされています。注釈
named
DB-API パラメータ・スタイルもサポートされています。
- sqlite3.threadsafety¶
sqlite3
モジュールがサポートするスレッドセーフのレベルを示す、DB-API 2.0 で必要な整数定数。 この属性は、背後の SQLite ライブラリのコンパイル時のデフォルトの SQLite スレッド・モード (threading mode)に基づいて設定されます。 SQLite のスレッド・モードは以下のとおりです:シングル・スレッド: このモードでは、すべてのミューテックスが無効になり、一度に複数のスレッドで SQLite を使用するのは安全ではありません。
マルチ・スレッド: このモードでは、 1 つのデータベース接続が 2 つ以上のスレッドで同時に使用されない限り、複数のスレッドで SQLite を安全に使用できます。
直列化: 直列化(serialized)モードでは、 SQLite を複数のスレッドで制限なく安全に使用できます。
SQLite スレッド・モードと、 DB-API 2.0 のスレッドセーフ・レベルとの対応は以下のとおりです:
SQLite スレッド・モード
DB-API 2.0 での意味
シングル・スレッド
0
0
スレッドはモジュールを共有できません
マルチ・スレッド
1
2
スレッドはモジュールを共有できますが、接続は共有できません
直列化
3
1
スレッドは、モジュールや接続やカーソルを共有できます
バージョン 3.11 で変更:
1
とハード・コーディングする代わりに threadsafety を動的に設定します。
- sqlite3.version¶
文字列
としての、このモジュールのバージョン番号。これは SQLite ライブラリのバージョン番号ではありません。Deprecated since version 3.12, will be removed in version 3.14: この定数は、
sqlite3
へのアップストリーム変更に使用されていたサードパーティ・ライブラリである、pysqlite
パッケージのバージョン番号を反映していました。今やこれには何の意味も無いし実用的な価値もありません。
- sqlite3.version_info¶
整数
のタプル
としての、このモジュールのバージョン番号。これは SQLite ライブラリのバージョン番号ではありません。Deprecated since version 3.12, will be removed in version 3.14: この定数は、
sqlite3
へのアップストリーム変更に使用されていたサードパーティ・ライブラリである、pysqlite
パッケージのバージョン番号を反映していました。今やこれには何の意味も無いし実用的な価値もありません。
- sqlite3.SQLITE_DBCONFIG_DEFENSIVE¶
- sqlite3.SQLITE_DBCONFIG_DQS_DDL¶
- sqlite3.SQLITE_DBCONFIG_DQS_DML¶
- sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY¶
- sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER¶
- sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION¶
- sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG¶
- sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER¶
- sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW¶
- sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE¶
- sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT¶
- sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE¶
- sqlite3.SQLITE_DBCONFIG_RESET_DATABASE¶
- sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP¶
- sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA¶
- sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA¶
これらの定数は、
Connection.setconfig()
メソッド やgetconfig()
メソッドで使用されます。これらの定数が利用できるかどうかは、 Python にコンパイルされた SQLite のバージョンによって異なります。
Added in version 3.12.
参考
- https://www.sqlite.org/c3ref/c_dbconfig_defensive.html
SQLite docs: Database Connection Configuration Options
Connection オブジェクト¶
- class sqlite3.Connection¶
開いた SQLite データベースの各々は、
sqlite3.connect()
を使用して作成されるConnection
オブジェクトによって表されます。Connection
オブジェクトの主な目的はCursor
オブジェクトの作成と トランザクション制御 です。バージョン 3.13 で変更: A
ResourceWarning
is emitted ifclose()
is not called before aConnection
object is deleted.SQLite データベース接続(connection)には、以下の属性とメソッドがあります:
- cursor(factory=Cursor)¶
Cursor
オブジェクトを作成して返します。 cursor メソッドは、単一のオプション・パラメーター factory を受け入れます。 factory を指定する場合、これはCursor
またはそのサブクラスのインスタンスを返す 呼び出し可能オブジェクト である必要があります。
- blobopen(table, column, row, /, *, readonly=False, name='main')¶
既存の BLOB への
Blob
ハンドルを開きます。- パラメータ:
- 例外:
OperationalError --
WITHOUT ROWID
テーブルで BLOB を開こうとしたとき。- 戻り値の型:
注釈
Blob
クラスを使用して BLOB のサイズを変更することはできません。 SQL 関数zeroblob
を使用すると、固定サイズのブロブを作成します。Added in version 3.11.
- commit()¶
保留中のトランザクションをデータベースにコミットします。
autocommit
がTrue
または開いているトランザクションがない場合、このメソッドは何も行いません。autocommit
がFalse
の場合に保留中のトランザクションがこのメソッドによってコミットされた場合、新しいトランザクションが暗黙に開かれます。
- rollback()¶
保留中のトランザクションの先頭にロールバックします。
autocommit
がTrue
または開いているトランザクションがない場合、このメソッドは何も行いません。autocommit
がFalse
の場合に保留中のトランザクションがこのメソッドによってロールバックされた場合、新しいトランザクションが暗黙に開かれます。
- close()¶
データベース接続を閉じます。
autocommit
がFalse
の場合、保留中のトランザクションは暗黙にロールバックされます。autocommit
がTrue
またはLEGACY_TRANSACTION_CONTROL
の場合、暗黙のトランザクション制御は実行されませんので、保留中の変更が失われないように、データベース接続を閉じる前に必ずcommit()
を行ってください。
- execute(sql, parameters=(), /)¶
新しい
Cursor
オブジェクトを作成し、指定の sql と parameters でexecute()
を呼び出します。新しいカーソル・オブジェクトを返します。
- executemany(sql, parameters, /)¶
新しい
Cursor
オブジェクトを作成し、与えられた sql と parameters でexecutemany()
を呼び出します。新しいカーソル・オブジェクトを返します。
- executescript(sql_script, /)¶
新しい
Cursor
オブジェクトを作成し、指定された sql_script でexecutescript()
を呼び出します。新しいカーソル・オブジェクトを返します。
- create_function(name, narg, func, *, deterministic=False)¶
ユーザ定義 SQL 関数を作成または削除します。
- パラメータ:
name (str) -- SQL 関数の名前。
narg (int) -- SQL 関数が受け入れることができる引数の数。
-1
を指定すると、任意の数の引数を取ることができます。func (callback | None) -- この SQL 関数が呼び出されたときに起動される 呼び出し可能オブジェクト 。 この呼び出し可能オブジェクトは、 SQLite によってネイティブにサポートされる型 を返すす必要があります。 既存の SQL 関数を削除するには、
None
に設定します。deterministic (bool) --
True
の場合、作成された SQL 関数は決定論的(deterministic : 入力が同一なら常に同一の答えを返す)としてマークされ、SQLite が追加の最適化を実行できるようになります。
バージョン 3.8 で変更: Added the deterministic parameter.
例:
>>> import hashlib >>> def md5sum(t): ... return hashlib.md5(t).hexdigest() >>> con = sqlite3.connect(":memory:") >>> con.create_function("md5", 1, md5sum) >>> for row in con.execute("SELECT md5(?)", (b"foo",)): ... print(row) ('acbd18db4cc2f85cedef654fccc4a4d8',) >>> con.close()
バージョン 3.13 で変更: Passing name, narg, and func as keyword arguments is deprecated. These parameters will become positional-only in Python 3.15.
- create_aggregate(name, n_arg, aggregate_class)¶
ユーザ定義集計関数を作成または削除します。
- パラメータ:
name (str) -- SQL 集計関数の名前。
n_arg (int) -- SQL 集計関数が受け入れることができる引数の数。
-1
を指定すると、任意の数の引数を取ることができます。aggregate_class (class | None) --
クラスは以下のメソッドを実装する必要があります:
step()
: 集計に行(row)を足し込みます。finalize()
: 集計の最終結果を SQLite でネイティブにサポートされている型 として返します。
step()
メソッドが受け入れなければならない引数の数は n_arg によって制御されます。既存の SQL 集計関数を削除するには、
None
に設定します。
例:
class MySum: def __init__(self): self.count = 0 def step(self, value): self.count += value def finalize(self): return self.count con = sqlite3.connect(":memory:") con.create_aggregate("mysum", 1, MySum) cur = con.execute("CREATE TABLE test(i)") cur.execute("INSERT INTO test(i) VALUES(1)") cur.execute("INSERT INTO test(i) VALUES(2)") cur.execute("SELECT mysum(i) FROM test") print(cur.fetchone()[0]) con.close()
バージョン 3.13 で変更: Passing name, n_arg, and aggregate_class as keyword arguments is deprecated. These parameters will become positional-only in Python 3.15.
- create_window_function(name, num_params, aggregate_class, /)¶
ユーザー定義の集計ウインドウ関数を作成または削除します。
- パラメータ:
name (str) -- 作成または削除する SQL 集計ウインドウ関数の名前。
num_params (int) -- SQL 集計ウィンドウ関数が受け入れることができる引数の数。
-1
を指定した場合、任意の数の引数を取ることができます。aggregate_class (class | None) --
クラスは以下のメソッドを実装する必要があります:
step()
: 現在のウィンドウに行を足し込みます。value()
: 集計の現在の値を返します。inverse()
: 現在のウインドウから指定の行(row)の分を削除します。finalize()
: 集計の最終結果を SQLite でネイティブにサポートされている型 として返します。
step()
メソッドとvalue()
メソッドが受け入れなければならない引数の数は num_params によって制御されます。None
に設定すると、既存の SQL 集計ウィンドウ関数が削除されます。
- 例外:
NotSupportedError -- 集計ウィンドウ関数をサポートしていない 3.25.0 より古いバージョンの SQLite で使用した場合に送出されます。
Added in version 3.11.
例:
# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc class WindowSumInt: def __init__(self): self.count = 0 def step(self, value): """Add a row to the current window.""" self.count += value def value(self): """Return the current value of the aggregate.""" return self.count def inverse(self, value): """Remove a row from the current window.""" self.count -= value def finalize(self): """Return the final value of the aggregate. Any clean-up actions should be placed here. """ return self.count con = sqlite3.connect(":memory:") cur = con.execute("CREATE TABLE test(x, y)") values = [ ("a", 4), ("b", 5), ("c", 3), ("d", 8), ("e", 1), ] cur.executemany("INSERT INTO test VALUES(?, ?)", values) con.create_window_function("sumint", 1, WindowSumInt) cur.execute(""" SELECT x, sumint(y) OVER ( ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING ) AS sum_y FROM test ORDER BY x """) print(cur.fetchall()) con.close()
- create_collation(name, callable, /)¶
照合関数(collating function) callable を使用して name という名前の照合(collation)を作成します。 callable には 2 つの
文字列
引数が渡され、整数
を返す必要があります:1 番目の文字列が 2 番目の文字列よりも高い順位ならば
1
を返す1 番目の文字列が 2 番目の文字列よりも低い順位ならば
-1
を返す1 番目の文字列と 2 番目の文字列が同じ順位ならば
0
を返す
以下は逆順での照合例です:
def collate_reverse(string1, string2): if string1 == string2: return 0 elif string1 < string2: return 1 else: return -1 con = sqlite3.connect(":memory:") con.create_collation("reverse", collate_reverse) cur = con.execute("CREATE TABLE test(x)") cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)]) cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse") for row in cur: print(row) con.close()
照合関数を削除するには callable を
None
に設定します。バージョン 3.11 で変更: 照合の名前には任意のユニコード文字を含めることができます。 以前は ASCII 文字のみが許可されていました。
- interrupt()¶
このメソッドを別のスレッドから呼び出して、この接続(connection)で、実行中のすべてのクエリを中止(abort)させます。 中止(abort)させられたクエリは
OperationalError
を送出します。
- set_authorizer(authorizer_callback)¶
データベース内のテーブルの列(column)にアクセスしようとするたびに起動される 呼び出し可能オブジェクト authorizer_callback を登録します。 このコールバックは背後の SQLite ライブラリによって列(column)へのアクセスがどのように処理されるかを通知するために、
SQLITE_OK
またはSQLITE_DENY
またはSQLITE_IGNORE
のいずれかを返さなければなりません。コールバックの最初の引数は、承認(authorize)される操作の種類を示します。 2 番目と 3 番目の引数は、最初の引数に応じて、引数または
None
になります。 4 番目の引数は、該当する場合、データベースの名前("main" や "temp" 等)です。 5 番目の引数は、 アクセス試行を担当する最も内側のトリガーまたはビューの名前です。このアクセス試行が入力 SQL コードから直接行われた場合はNone
です。最初の引数に指定可能な値と、 最初の引数に応じた 2 番目と 3 番目の引数の意味については、 SQLite のドキュメントを参照してください。 必要なすべての定数は
sqlite3
モジュールで利用できます。authorizer_callback として
None
を渡すと、承認機構(authorizer)が無効になります。バージョン 3.11 で変更:
None
を使用して承認機構(authorizer)を無効にするサポートが追加されました。バージョン 3.13 で変更: Passing authorizer_callback as a keyword argument is deprecated. The parameter will become positional-only in Python 3.15.
- set_progress_handler(progress_handler, n)¶
SQLite 仮想マシンの命令を n 個実行するごとに呼び出されるように、 呼び出し可能オブジェクト progress_handler を登録します。これは、 GUI の更新など、長時間実行される操作中に SQLite から呼び出されるようにしたい場合に便利です。
以前にインストールした progress ハンドラーをクリアしたい場合は、 progress_handler に
None
を指定してメソッドを呼び出します。ハンドラー関数からゼロ以外の値を返すと、現在実行中のクエリを終了(terminate)し、
DatabaseError
例外を送出します。バージョン 3.13 で変更: Passing progress_handler as a keyword argument is deprecated. The parameter will become positional-only in Python 3.15.
- set_trace_callback(trace_callback)¶
SQLite バックエンドによって実際に実行される SQL 文ごとに起動される 呼び出し可能オブジェクト trace_callback を登録します。
コールバックに渡される唯一の引数は、(
str
として渡される)実行中のSQL文です。 コールバックの戻り値は無視されます。 バックエンドは、Cursor.execute()
メソッドに渡されたSQL文を実行するだけではないことに注意してください。sqlite3
モジュールの トランザクション管理 や、現在のデータベース内で定義されたトリガーの実行その他も行います。trace_callback として
None
を渡すと、トレース・コールバックが無効になります。注釈
トレース・コールバックで送出した例外は伝播されません。 開発およびデバッグの補助として、
enable_callback_tracebacks()
を使用して、トレース・コールバックで送出した例外からのトレースバックの出力を有効にします。Added in version 3.3.
バージョン 3.13 で変更: Passing trace_callback as a keyword argument is deprecated. The parameter will become positional-only in Python 3.15.
- enable_load_extension(enabled, /)¶
enabled が
True
の場合、 SQLite エンジンが共有ライブラリから SQLite 拡張機能をロードできるようにします。True
以外の場合は、 SQLite 拡張機能の読み込みを許可しません。 SQLite 拡張機能では、新しい関数の定義、または集計の定義、またはまったく新しい仮想テーブルの実装を定義できます。 よく知られている拡張機能の 1 つは、SQLite と共に配布される全文検索拡張機能です。注釈
sqlite3
モジュールは、デフォルトではロード可能な拡張機能をサポートするようにビルドされていません。一部のプラットフォーム(特に macOS)には、この機能なしでコンパイルされた SQLite ライブラリがあるためです。 ロード可能な拡張機能のサポートを得るには、 configure に--enable-loadable-sqlite-extensions
オプションを渡す必要があります。引数
connection
,enabled
を指定して 監査イベントsqlite3.enable_load_extension
を送出します。Added in version 3.2.
バージョン 3.10 で変更:
sqlite3.enable_load_extension
監査イベントを追加しました。con.enable_load_extension(True) # Load the fulltext search extension con.execute("select load_extension('./fts3.so')") # alternatively you can load the extension using an API call: # con.load_extension("./fts3.so") # disable extension loading again con.enable_load_extension(False) # example from SQLite wiki con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)") con.executescript(""" INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes'); INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery'); INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour'); INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter'); """) for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"): print(row)
- load_extension(path, /, *, entrypoint=None)¶
共有ライブラリから SQLite 拡張機能(extension)をロードします。このメソッドを呼び出す前に
enable_load_extension()
で拡張機能の読み込みを有効にしてください。- パラメータ:
path (str) -- SQLite 拡張機能(extension)へのパス(path)。
entrypoint (str | None) -- エントリ・ポイント名。
None
(デフォルト) の場合、 SQLite は自分自身でエントリ・ポイント名を推測します。 詳細については、SQLite ドキュメント Loading an Extension を参照してください。
引数
connection
,path
を指定して 監査イベントsqlite3.load_extension
を送出します。Added in version 3.2.
バージョン 3.10 で変更:
sqlite3.load_extension
監査イベントを追加しました。バージョン 3.12 で変更: Added the entrypoint parameter.
- iterdump(*, filter=None)¶
データベースを SQL ソース・コードとしてダンプする iterator を返します。 後で復元するためにメモリ内データベースを保存する場合に便利です。 sqlite3 シェルの
.dump
コマンドに似ています。- パラメータ:
filter (str | None) -- An optional
LIKE
pattern for database objects to dump, e.g.prefix_%
. IfNone
(the default), all database objects will be included.
例:
# Convert file example.db to SQL dump file dump.sql con = sqlite3.connect('example.db') with open('dump.sql', 'w') as f: for line in con.iterdump(): f.write('%s\n' % line) con.close()
バージョン 3.13 で変更: filter パラメータが追加されました。
- backup(target, *, pages=-1, progress=None, name='main', sleep=0.250)¶
SQLite データベースのバックアップを作成します。
データベースが他のクライアントによってアクセスされている場合、または同一の接続によって並行にアクセスされている場合でも機能します。
- パラメータ:
target (Connection) -- バックアップ先のデータベース接続(connection)。
pages (int) -- 一度にコピーするページ数。
0
以下の場合、データベース全体がワンステップでコピーされます。 デフォルトは-1
です。progress (callback | None) -- 呼び出し可能オブジェクト を設定すると、バックアップの指定ページ数単位の反復ごとに 3 つの整数引数で呼び出されます。 status は、最後の反復時のステータスで、 remaining はまだコピーされていない残りのページ数で、 total はコピーされるページの合計です。 デフォルトは
None
です。name (str) -- バックアップするデータベース名。
"main"
(メイン・データベース。これがデフォルトです)、または"temp"
(一時データベース)、 またはATTACH DATABASE
SQL文を使用して取り付けられたカスタム・データベース名の、いずれかです。sleep (float) -- バックアップの指定ページ数単位の反復ごとにスリープする秒数。
例 1. 既存のデータベースを別のデータベースにコピーします:
def progress(status, remaining, total): print(f'Copied {total-remaining} of {total} pages...') src = sqlite3.connect('example.db') dst = sqlite3.connect('backup.db') with dst: src.backup(dst, pages=1, progress=progress) dst.close() src.close()
例 2. 既存のデータベースを臨時コピー(transient copy)にコピーします。
src = sqlite3.connect('example.db') dst = sqlite3.connect(':memory:') src.backup(dst) dst.close() src.close()
Added in version 3.7.
- getlimit(category, /)¶
接続(connection)の実行時制限を取得します。
- パラメータ:
category (int) -- 問い合わせを行う実行時制限カテゴリー(SQLite limit category)。
- 戻り値の型:
- 例外:
ProgrammingError -- category に、 背後の SQLite ライブラリが認識できないカテゴリーを指定した場合に送出されます。
例:
Connection
のcon
の SQL 文の最大長を照会します (デフォルトは 1000000000 です):>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH) 1000000000
Added in version 3.11.
- setlimit(category, limit, /)¶
接続の実行時制限を設定します。 コンパイル時上限を超えて制限を増やそうとすると、 暗黙のうちにコンパイル時上限に切り捨てられます。 制限が変更されたかどうかに関係なく、 制限の以前の値が返されます。
- パラメータ:
category (int) -- SQLite limit category を設定する。
limit (int) -- 新しい制限の値。 負数の場合、 現在の制限は変更されません。
- 戻り値の型:
- 例外:
ProgrammingError -- category に、 背後の SQLite ライブラリが認識できないカテゴリーを指定した場合に送出されます。
Connection
のcon
に対して、取り付けられるデータベース(attached databases)の数を 1 に制限します (デフォルトの制限は 10 です):>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1) 10 >>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED) 1
Added in version 3.11.
- getconfig(op, /)¶
ブール値の接続構成オプションを問い合わせます。
- パラメータ:
op (int) -- SQLITE_DBCONFIG code を指定します。
- 戻り値の型:
Added in version 3.12.
- setconfig(op, enable=True, /)¶
ブール値の接続構成オプションを設定します。
- パラメータ:
op (int) -- SQLITE_DBCONFIG code を指定します。
enable (bool) -- 設定オプションを有効にする必要がある場合は
True
(デフォルト)。 無効にする場合はFalse
を指定します。
Added in version 3.12.
- serialize(*, name='main')¶
データベースを
bytes
オブジェクトに直列化(serialize)します。 通常のディスク上のデータベース・ファイルの場合、 直列化はディスク・ファイルの単なるコピーです。 インメモリ・データベースまたは "temp" データベースの場合、 直列化は、 そのデータベースがディスクにバックアップされた場合にディスクに書き込まれるバイト・シーケンスと同じです。注釈
このメソッドは、 背後の SQLite ライブラリに直列化 API がある場合にのみ使用できます。
Added in version 3.11.
- deserialize(data, /, *, name='main')¶
直列化
されたデータベースをConnection
に、 脱直列化(deserialize)します。 このメソッドにより、 データベース接続はデータベース name から切断され、そして、 data に含まれる直列化データに基づいて、 データベース name がインメモリ・データベースとして再度開かれます。- パラメータ:
- 例外:
OperationalError -- データベース接続が読み取りトランザクションやバックアップ操作中の場合。
DatabaseError -- data に有効な SQLite データベースが含まれていない場合。
OverflowError --
len(data)
が2**63 - 1
より大きい場合。
注釈
このメソッドは、 背後の SQLite ライブラリに脱直列化 API がある場合にのみ使用できます。
Added in version 3.11.
- autocommit¶
この属性は、 PEP 249 対応のトランザクションの振る舞いを制御します。
autocommit
には以下の 3 つの値が指定できます:False
: PEP 249 対応のトランザクションの振る舞いを選びます。 これは、sqlite3
が、 トランザクションが常に開いていることを保証することを意味します。トランザクションを閉じるには、commit()
やrollback()
を使用します。これが
autocommit
の推奨値です。True
: SQLite の autocommit mode を使用します。このモードではcommit()
やrollback()
は効果がありません。LEGACY_TRANSACTION_CONTROL
: Python 3.12 より前(PEP 249 非対応)のトランザクション制御。 詳細についてはisolation_level
を参照してください。これが、今のところは、
autocommit
のデフォルト値です。
autocommit
をFalse
に変更すると新しいトランザクションが開き、True
に変更すると保留中のトランザクションがコミットされます。詳細は autocommit 属性に依るトランザクション制御 を参照してください。
注釈
isolation_level
属性は、autocommit
の値がLEGACY_TRANSACTION_CONTROL
でない限り、効果がありません。Added in version 3.12.
- in_transaction¶
この読み取り専用属性は、低レベルの SQLite autocommit mode に対応します。
トランザクションがアクティブな場合 (コミットされていない変更がある場合) は
True
、それ以外の場合はFalse
です。Added in version 3.2.
- isolation_level¶
sqlite3
の 旧来のトランザクション処理モード を制御します。None
に設定すると、トランザクションは暗黙に開かれることはありません。背後の SQLite の SQLite transaction behaviour に対応する"DEFERRED"
または"IMMEDIATE"
または"EXCLUSIVE"
のいずれかに設定すると、 暗黙のトランザクション管理 が実行されます。connect()
の isolation_level パラメーターでオーバーライドされない場合、 デフォルトは""
で、 これは"DEFERRED"
の別名です。注釈
トランザクション処理を制御するには、
isolation_level
を使用するよりもautocommit
を使用することをお勧めします。autocommit
がLEGACY_TRANSACTION_CONTROL
(これがデフォルトです)に設定されていない限り、isolation_level
は効果がありません。
- row_factory¶
この接続から作成された
Cursor
オブジェクトの初期row_factory
。この属性に割り当てを行っても、 この接続に属する、すでに存在するカーソルのrow_factory
には影響せず、 この属性に割り当てを行った後に作成する新しいカーソルのみに影響します。 デフォルトではNone
です。つまり、各行はタプル
として返されます。詳細は 行工場(row factories)の作成方法と使用方法 をご覧下さい。
- text_factory¶
bytes
のパラメータを受け取り、そのテキスト表現を返す 呼び出し可能オブジェクト です。呼び出し可能オブジェクトはTEXT
データ型である SQLite 値に対して呼び出されます。 デフォルトでは、 この属性はstr
に設定されています。See How to handle non-UTF-8 text encodings for more details.
- total_changes¶
データベース接続が開かれてから、変更または挿入または削除されたデータベース行の総数を返します。
Cursor オブジェクト¶
Cursor
オブジェクトは、 SQL 文を実行し、 取得操作(fetch operation)のコンテキストを管理するために使用されるデータベース・カーソル(database cursor)を表します。カーソルは、Connection.cursor()
または 接続(connection)ショートカット・メソッド の、いずれかを使用して作成されます。カーソル・オブジェクトは イテレータ です。つまり、
SELECT
クエリに対してexecute()
した場合、結果の行(rows)を取得するためには、カーソルを単純に反復(iterate)できます:for row in cur.execute("SELECT t FROM data"): print(row)
- class sqlite3.Cursor¶
Cursor
インスタンスは以下の属性やメソッドを持ちます。- execute(sql, parameters=(), /)¶
Execute a single SQL statement, optionally binding Python values using placeholders.
- パラメータ:
sql (str) -- 単一の SQL 文。
parameters (
dict
| sequence) -- sql のプレースホルダに結び付け(bind)する Python 値。 名前付きプレースホルダが使用されている場合はdict
です。 名前のないプレースホルダが使用されている場合は sequence です。 プレースホルダを使用して SQL クエリに値を結び付ける方法 を参照してください。
- 例外:
ProgrammingError -- sql に複数の SQL 文が含まれている場合。
autocommit
がLEGACY_TRANSACTION_CONTROL
で、かつ、isolation_level
がNone
で無く、 かつ、 sql がINSERT
またはUPDATE
またはDELETE
またはREPLACE
文で、かつ、開いているトランザクションがない場合、 sql を実行する前にトランザクションが暗黙に開かれます。Deprecated since version 3.12, will be removed in version 3.14: 名前付きプレースホルダー が使用され、かつ、パラメーターが
dict
ではなくシーケンスである場合、DeprecationWarning
を送出します。 Python 3.14 以降では、代わりにProgrammingError
を送出します。複数の SQL 文を実行するには
executescript()
を使用します。
- executemany(sql, parameters, /)¶
parameters のすべての item に対して、 パラメーター化 された DML SQL 文である sql を繰り返し実行します。
execute()
と同一の暗黙のトランザクション処理を使用します。- パラメータ:
sql (str) -- 単一の DML 文。
parameters (iterable) -- sql のプレースホルダに結び付け(bind)するためのパラメータの iterable 。 プレースホルダを使用して SQL クエリに値を結び付ける方法 参照。
- 例外:
ProgrammingError -- If sql contains more than one SQL statement, or is not a DML statement.
例:
rows = [ ("row1",), ("row2",), ] # cur is an sqlite3.Cursor object cur.executemany("INSERT INTO data VALUES(?)", rows)
注釈
RETURNING 句(RETURNING clauses)を含むDML文を含め、結果の行はすべて破棄されます。
Deprecated since version 3.12, will be removed in version 3.14: 名前付きプレースホルダー が使用され、かつ、パラメーターが
dict
ではなくシーケンスである場合、DeprecationWarning
を送出します。 Python 3.14 以降では、代わりにProgrammingError
を送出します。
- executescript(sql_script, /)¶
sql_script 内の複数のSQL文を実行します。
autocommit
がLEGACY_TRANSACTION_CONTROL
で、かつ、保留中のトランザクションがある場合、暗黙のCOMMIT
文が最初に実行されます。その他の暗黙のトランザクション制御は実行されませんので、トランザクション制御を sql_script に追加しなければなりません。sql_script は
文字列
でなければなりません。例:
# cur is an sqlite3.Cursor object cur.executescript(""" BEGIN; CREATE TABLE person(firstname, lastname, age); CREATE TABLE book(title, author, published); CREATE TABLE publisher(name, address); COMMIT; """)
- fetchone()¶
row_factory
がNone
の場合、 次の行のクエリ結果セットをタプル
として返します。それ以外の場合は、 それを行工場(row factory)に渡し、 その結果を返します。 これ以上データが無い場合はNone
を返します。
- fetchmany(size=cursor.arraysize)¶
クエリ結果の次の行セットを
list
として返します。行がそれ以上ない場合は、空のリストを返します。呼び出しごとに取得する行数は、size パラメーターで指定されます。 size が指定されていない場合、
arraysize
が取得する行数を決定します。有効な行の数が size 未満の場合は、有効な数の行が返されます。size 引数とパフォーマンスの関係についての注意です。パフォーマンスを最適化するためには、大抵、 arraysize 属性を利用するのがベストです。 size 引数を利用したのであれば、次回の
fetchmany()
の呼び出しでも size 引数に同一の値を指定するのがのがベストです。
- fetchall()¶
クエリ結果の(残りの)すべての行を
list
として返します。 有効な行がない場合は、空のリストを返します。arraysize
属性は、この操作のパフォーマンスに影響を与える可能性があることに注意してください。
- close()¶
(
__del__
が呼び出される時ではなく、) 今すぐカーソルを閉じます。この時点から、このカーソルは使用できなくなります。今後、このカーソルで何らかの操作を試みると、
ProgrammingError
例外が送出されます。
- setinputsizes(sizes, /)¶
DB-API で必要です。
sqlite3
では何もしません。
- setoutputsize(size, column=None, /)¶
DB-API で必要です。
sqlite3
では何もしません。
- arraysize¶
fetchmany()
によって返される行(row)数を制御する、読み取りと書き込みが可能な属性。 デフォルト値は 1 で、これは呼び出しごとに 1 行が取得されることを意味します。
- connection¶
カーソルが属する SQLite データベース
Connection
を提供する読み取り専用属性。con.cursor()
と呼び出して作成したCursor
オブジェクトには、con を参照するconnection
属性があります:>>> con = sqlite3.connect(":memory:") >>> cur = con.cursor() >>> cur.connection == con True >>> con.close()
- description¶
最後のクエリの列(column)名を提供する読み取り専用属性。 Python DB API との互換性を維持するために、各列ごとに 7 項目のタプルで、先頭の項目が列名、残りの6項目が
None
です。この属性は
SELECT
文にマッチする行(row)が1つもなかった場合でもセットされます。
- lastrowid¶
最後に挿入された行の行 ID (row id) を提供する読み取り専用属性。
execute()
でINSERT
またはREPLACE
文が成功した後にのみ更新されます。他のSQL文や、executemany()
の後や、executescript()
の後や、 挿入が失敗した場合、lastrowid
の値は変更されません。lastrowid
の初期値はNone
です。注釈
WITHOUT ROWID
テーブルへの挿入(insert)は記録されません。バージョン 3.6 で変更:
REPLACE
文のサポートが追加されました。
- rowcount¶
INSERT
やUPDATE
やDELETE
やREPLACE
文で変更された行数を提供する読み取り専用属性。 CTE クエリを含む他のSQL文は-1
です。execute()
とexecutemany()
メソッドのみにおいて、 SQL文(statement)実行の完了後に更新されます。 なぜならrowcount
を更新するためには、結果の行を取得(fetch)しなければならないからです。
- row_factory¶
この
カーソル
から取得された行の表現方法を制御します。None
の場合、行はタプル
として表されます。sqlite3.Row
に設定することもできます。 そしてまた、Cursor
オブジェクトと、 行の値のタプル
の、 2 つの引数を受け取り、 SQLite の行(row)を表すカスタム・オブジェクトを返す、 呼び出し可能オブジェクト に設定することもできます。カーソル・オブジェクト
の作成時にConnection.row_factory
の値をこの属性のデフォルト値として設定します。この属性に割り当てても、親接続(parent connection)のConnection.row_factory
には影響しません。詳細は 行工場(row factories)の作成方法と使用方法 をご覧下さい。
Row オブジェクト¶
- class sqlite3.Row¶
Row
インスタンスは、Connection
オブジェクトの、高度に最適化されたrow_factory
の役割をします。 反復(iteration)や、等しいかどうかのテスト(equality testing)や、len()
関数や 、 列名(column name)とインデックスによる マッピング のアクセスを、サポートします。列名(column names)と値(values)が全く同一である 2 つの
Row
オブジェクトを比較すると、等しいと見なされます。詳細は 行工場(row factories)の作成方法と使用方法 をご覧下さい。
- keys()¶
列名(column names)の
リスト
を文字列
として返します。 クエリの直後であれば、それはCursor.description
の各タプルの最初のメンバーです。
バージョン 3.5 で変更: スライスがサポートされました。
Blob オブジェクト¶
- class sqlite3.Blob¶
Added in version 3.11.
Blob
インスタンスは、 SQLite の BLOB とデータを読み書きできる file-like object です。len(blob)
を呼び出して、 Blob のサイズ (バイト数) を取得します。 Blob データに直接アクセスするには、インデックスと スライス を使用します。Blob
を コンテキストマネージャ として使用して、 使用後に Blob ハンドルが確実に閉じられるようにします。con = sqlite3.connect(":memory:") con.execute("CREATE TABLE test(blob_col blob)") con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))") # Write to our blob, using two write operations: with con.blobopen("test", "blob_col", 1) as blob: blob.write(b"hello, ") blob.write(b"world.") # Modify the first and last bytes of our blob blob[0] = ord("H") blob[-1] = ord("!") # Read the contents of our blob with con.blobopen("test", "blob_col", 1) as blob: greeting = blob.read() print(greeting) # outputs "b'Hello, world!'" con.close()
- read(length=-1, /)¶
BLOB の現在のオフセット位置から length バイトのデータを読み取り返ます。 BLOB の現在のオフセット位置から末尾までの残りが length バイトよりも少ない場合、末尾までのデータを読み取ります。 length が指定されていない場合、 または負数の場合、
read()
は BLOB の現在のオフセット位置から末尾までのデータを読み取ります。
- write(data, /)¶
BLOB の現在のオフセット位置から data を書き込みます。 この関数では BLOB の長さを変更できません。 BLOB の末尾を超えて書き込もうとすると
ValueError
を送出します。
- tell()¶
BLOBの現在のオフセット位置(current access position)を返します。
- seek(offset, origin=os.SEEK_SET, /)¶
Set the current access position of the blob to offset. The origin argument defaults to
os.SEEK_SET
(absolute blob positioning). Other values for origin areos.SEEK_CUR
(seek relative to the current position) andos.SEEK_END
(seek relative to the blob’s end).
PrepareProtocol オブジェクト¶
- class sqlite3.PrepareProtocol¶
PrepareProtocol 型の唯一の目的は、 SQLite でネイティブにサポートされている型 に オブジェクト自身で適合(adapt) できるオブジェクトの PEP 246 スタイルの適合プロトコルとして機能することです。
例外¶
例外の階層は DB-API 2.0 (PEP 249) で定義されています。
- exception sqlite3.Warning¶
この例外は、現在
sqlite3
モジュールでは送出しませんが、ユーザー定義関数が挿入処理中にデータを切り捨てる場合など、sqlite3
を使用するアプリケーションによって送出されるる可能性があります。Warning
はException
のサブクラスです。
- exception sqlite3.Error¶
このモジュールの他の例外の基底となるクラス。 これを使用すると、1 つの
except
文ですべてのエラーをキャッチできます。Error
はException
のサブクラスです。例外が SQLite ライブラリ内で発生した場合、 以下の 2 つの属性が例外に追加されます:
- sqlite_errorcode¶
SQLite API からの数値エラー・コード
Added in version 3.11.
- sqlite_errorname¶
SQLite API からの数値エラー・コードの記号名
Added in version 3.11.
- exception sqlite3.InterfaceError¶
低レベルの SQLite C API の誤用により送出される例外。 つまり、この例外が送出された場合、おそらく
sqlite3
モジュールのバグを示しています。InterfaceError
はError
のサブクラスです。
- exception sqlite3.DatabaseError¶
データベースに関連するエラーに対して送出される例外。 これは、いくつかの種類のデータベース・エラーの基底の例外として機能します。 これを特殊化(specialise)したサブクラスを介して暗黙的にのみ送出されます。
DatabaseError
はError
のサブクラスです。
- exception sqlite3.DataError¶
範囲外の数値や長すぎる文字列など、処理されたデータの問題によって発生したエラーに対して送出される例外。
DataError
はDatabaseError
のサブクラスです。
- exception sqlite3.OperationalError¶
データベースの操作に関連し、必ずしもプログラマの制御下にないエラーに対して発生する例外。 たとえば、データベース・パスが見つからないとか、トランザクションを処理できませんでした等。
OperationalError
はDatabaseError
のサブクラスです。
- exception sqlite3.IntegrityError¶
データベースの参照整合性が影響を受ける場合に発生する例外。 たとえば外部キーのチェック(foreign key check)が失敗したとき。
DatabaseError
のサブクラスです。
- exception sqlite3.InternalError¶
SQLite が内部エラーに遭遇したときに発生する例外。 これが送出された場合、ランタイム SQLite ライブラリに問題があることを示している可能性があります。
InternalError
はDatabaseError
のサブクラスです。
- exception sqlite3.ProgrammingError¶
sqlite3
API プログラミング・エラーに対して送出される例外。たとえば、クエリに間違った数のバインディング(結び付け)を指定したり、閉じた後のConnection
を操作しようとしたりしたとき。ProgrammingError
はDatabaseError
のサブクラスです。
- exception sqlite3.NotSupportedError¶
メソッドまたはデータベース API が 背後の SQLite ライブラリでサポートしていない場合に送出される例外。たとえば、背後の SQLite ライブラリが決定論的関数(deterministic functions)をサポートしていない場合に、
create_function()
で deterministic をTrue
に設定したとき。NotSupportedError
はDatabaseError
のサブクラスです。
SQLite と Python の型¶
SQLite は以下の型をネイティブにサポートします: NULL
, INTEGER
, REAL
, TEXT
, BLOB
。
したがって、次の Python の型は問題なく SQLite に送り込めます:
Python の型 |
SQLite の型 |
---|---|
|
|
|
|
|
|
|
|
|
SQLite の型から Python の型へのデフォルトでの変換は以下の通りです:
SQLite の型 |
Python の型 |
---|---|
|
|
|
|
|
|
|
|
|
sqlite3
モジュールの型システムは 2 つの方法で拡張可能です。 オブジェクト適合関数(adapter) を介して SQLite データベースに追加の Python 型を格納できます。 または、 変換関数(converter) を介して sqlite3
モジュールが SQLite 型を Python 型に変換できます。
デフォルトの適合関数(adapters)とデフォルトの変換関数(converters)(非推奨)¶
注釈
デフォルトの適合関数(adapters)とデフォルトの変換関数(converters)は、 Python 3.12 以降非推奨になりました。代わりに、 適合関数と変換関数のレシピ集 を利用して、あなたのニーズに合わせて仕立てて下さい。
非推奨の、デフォルトの適合関数(adapters)とデフォルトの変換関数(converters)は以下のもので構成されています:
datetime.date
オブジェクトを ISO 8601 形式の文字列
にする適合関数(adapter)。datetime.datetime
オブジェクトを ISO 8601 形式の文字列にする適合関数(adapter)。"date" と 宣言された 型を
datetime.date
オブジェクトにする変換関数(converter)。"timestamp" と宣言された型を
datetime.datetime
オブジェクトにする変換関数(converter)。小数部分は 6 桁 (マイクロ秒の精度) に切り捨てられます。
注釈
デフォルトの "timestamp" 変換関数は、データベース内の UTC オフセットを無視し、常に素朴(naive)な datetime.datetime
オブジェクトを返します。 timestamp で UTC オフセットを保持するには、変換関数を無効のままにするか、あるいは、オフセット対応の変換関数を register_converter()
に登録します。
バージョン 3.12 で非推奨.
コマンドライン・インターフェース¶
sqlite3
モジュールは、単純な SQLite シェルを提供するために、インタプリタで -m
スイッチを使用してスクリプトとして呼び出すことができます。引数は以下のとおりです:
python -m sqlite3 [-h] [-v] [filename] [sql]
.quit
または CTRL-D を入力するとシェルを終了(exit)します。
- -h, --help¶
CLI ヘルプを表示。
- -v, --version¶
背後の SQLite ライブラリのバージョンを出力します。
Added in version 3.12.
ハウツー・ガイド¶
プレースホルダを使用して SQL クエリに値を結び付ける方法¶
たいてい、SQL 操作は Python 変数の値を使う必要があります。しかし、 Python の文字列操作を使用してクエリを組み立てるのはSQLインジェクション攻撃(SQL injection attacks)に対して脆弱なので注意が必要です。たとえば、攻撃者は以下のように単純にシングルクォートを閉じて OR TRUE
を挿入してすべての行を選択できます:
>>> # Never do this -- insecure!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
>>> cur.execute(sql)
代わりに、DB-API のパラメータ割り当てを使います。クエリ文字列にPythonの変数を挿入するには、クエリ文字列中でプレースホルダを使用し、 かつ、 カーソルの execute()
メソッドの 2 番目の引数にPythonの変数を値の タプル
として指定することにより、 実際の値をクエリに割り当てます。
SQL 文では、疑問符 (qmark スタイル) または名前付きプレースホルダー (名前付きスタイル) の 2 種類のプレースホルダーのいずれかを使用できます。 qmark スタイルの場合、parameters は、 シーケンス でなければならず、シーケンスの長さがプレースホルダーの数と一致する必要があります。そうでなければ、 ProgrammingError
を送出します。名前付きスタイルの場合、 parameters は dict
(またはそのサブクラス) のインスタンスである必要があり、すべての名前付きパラメーターのキーが含まれている必要があります。余分な項目は無視されます。両方のスタイルの例を以下に示します。
con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE lang(name, first_appeared)")
# This is the named style used with executemany():
data = (
{"name": "C", "year": 1972},
{"name": "Fortran", "year": 1957},
{"name": "Python", "year": 1991},
{"name": "Go", "year": 2009},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)
# This is the qmark style used in a SELECT query:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()
注釈
PEP 249 numeric プレースホルダは サポートされていません 。 使用すると、名前付きプレースホルダとして解釈されます。
カスタム Python 型を SQLite 値に適合させる方法¶
SQLite は、 限られたデータ型のみをネイティブにサポートします。 カスタム Python 型を SQLite データベースに保存するには、 SQLite がネイティブに理解できる Python 型 のいずれかに 適合 (adapt)させます。
Python オブジェクトを SQLite の型に適合させる方法は 2 つあります。それは、オブジェクト自体を適合させる方法と、 adapter callable を使用する方法です。 後者は前者よりも優先されます。 カスタム型をエクスポートするライブラリの場合、 その型がそれ自体を適合させる事ができるようにすることが理にかなっている場合があります。 アプリケーション開発者としては、カスタム適合関数を登録して直接制御する方が理にかなっている場合もあります。
適合可能オブジェクトの書き方¶
直交座標系(Cartesian coordinate system)で x
と y
のペアで座標を表す、 Point
クラスがあるとします。 この x
と y
のペアはセミコロンで区切られたテキスト文字列としてデータベースに保存されます。 これは、適合した値を返す __conform__(self, protocol)
メソッドを追加することで実装できます。 protocol に渡されるオブジェクトは、 PrepareProtocol
型になります。
class Point:
def __init__(self, x, y):
self.x, self.y = x, y
def __conform__(self, protocol):
if protocol is sqlite3.PrepareProtocol:
return f"{self.x};{self.y}"
con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("SELECT ?", (Point(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()
適合用呼び出し可能オブジェクト(adapter callables)の登録方法¶
別の策としては、Python オブジェクトを SQLite 互換の型に変換する関数を作成することが挙げられます。 この関数は、 register_adapter()
を使用して登録できます。
class Point:
def __init__(self, x, y):
self.x, self.y = x, y
def adapt_point(point):
return f"{point.x};{point.y}"
sqlite3.register_adapter(Point, adapt_point)
con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()
SQLite 値をカスタム Python 型に変換する方法¶
適合関数(adapter)を使用すると、カスタム Python 型から SQLite 値に変換できます。SQLite 値 から カスタム Python 型に変換できるようにするためには、 変換関数 (converters)を使用します。
それでは Point
クラスの話に戻るとしましょう。 先程は x 座標と y 座標をセミコロンで区切られた文字列として SQLite に格納しました。
まず、 文字列をパラメーターとして受け取り、そこから Point
オブジェクトを構築する変換関数を定義します。
注釈
変換関数には、基になる SQLite データ型に関係なく、 常に bytes
オブジェクトで渡されます。
def convert_point(s):
x, y = map(float, s.split(b";"))
return Point(x, y)
与えられた SQLite 値をどの時点で変換すべきかを sqlite3
に伝える必要があります。これは、 connect()
の detect_types パラメータを使用して、データベースに接続する際に行います。 以下の 3 つの選択肢があります:
暗黙的: detect_types に
PARSE_DECLTYPES
と設定。明示的: detect_types に
PARSE_COLNAMES
と設定。両方: detect_types に
sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES
を設定。列名での指定は、宣言時の型よりも優先されます。
以下の例では、暗黙的なアプローチと明示的なアプローチについて表しています:
class Point:
def __init__(self, x, y):
self.x, self.y = x, y
def __repr__(self):
return f"Point({self.x}, {self.y})"
def adapt_point(point):
return f"{point.x};{point.y}"
def convert_point(s):
x, y = list(map(float, s.split(b";")))
return Point(x, y)
# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)
# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.execute("CREATE TABLE test(p point)")
cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute("SELECT p FROM test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()
# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.execute("CREATE TABLE test(p)")
cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute('SELECT p AS "p [point]" FROM test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()
適合関数と変換関数のレシピ集¶
この節では一般的な適合関数と変換関数のレシピを紹介します。
import datetime
import sqlite3
def adapt_date_iso(val):
"""Adapt datetime.date to ISO 8601 date."""
return val.isoformat()
def adapt_datetime_iso(val):
"""Adapt datetime.datetime to timezone-naive ISO 8601 date."""
return val.isoformat()
def adapt_datetime_epoch(val):
"""Adapt datetime.datetime to Unix timestamp."""
return int(val.timestamp())
sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)
def convert_date(val):
"""Convert ISO 8601 date to datetime.date object."""
return datetime.date.fromisoformat(val.decode())
def convert_datetime(val):
"""Convert ISO 8601 datetime to datetime.datetime object."""
return datetime.datetime.fromisoformat(val.decode())
def convert_timestamp(val):
"""Convert Unix epoch timestamp to datetime.datetime object."""
return datetime.datetime.fromtimestamp(int(val))
sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)
接続(connection)ショートカット・メソッドの使い方¶
Connection
クラスのメソッド execute()
と executemany()
と executescript()
を使うことで、 (しばしば余計な) Cursor
オブジェクトをわざわざ作り出さずに済むので、コードをより簡潔に書くことができます。 Cursor
オブジェクトは暗黙裡に生成され、ショートカット・メソッドの戻り値として受け取ることができます。この方法を使えば、 SELECT
文を実行してその結果について反復することが、 Connection
オブジェクトに対する呼び出し一つで行なえます。
# Create and fill the table.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(name, first_appeared)")
data = [
("C++", 1985),
("Objective-C", 1984),
]
con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)
# Print the table contents
for row in con.execute("SELECT name, first_appeared FROM lang"):
print(row)
print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")
# close() is not a shortcut method and it's not called automatically;
# the connection object should be closed manually
con.close()
接続(connection)コンテキストマネージャの使い方¶
Connection
オブジェクトは、コンテキスト・マネージャーとして使用でき、コンテキスト・マネージャーとして使用すると、 with
ブロックを離れるときに、開いているトランザクションを自動的にコミットまたはロールバックします。 with
文のブロックが例外なく終了すると、トランザクションはコミットされます。このコミットが失敗した、または、 with
文のブロックでキャッチされなかった例外が発生した場合、トランザクションはロールバックされます。 autocommit
が False
の場合、コミット後またはロールバック後に新しいトランザクションが暗黙に開かれます。
with
文のブロックを離れるときに開いているトランザクションがない、または、 autocommit
が True
の場合、コンテキスト・マネージャは何も行いません。
注釈
The context manager neither implicitly opens a new transaction
nor closes the connection. If you need a closing context manager, consider
using contextlib.closing()
.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")
# Successful, con.commit() is called automatically afterwards
with con:
con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
# con.rollback() is called after the with block finishes with an exception,
# the exception is still raised and must be caught
try:
with con:
con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
print("couldn't add Python twice")
# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
con.close()
SQLite URI の操作方法¶
URI の小技をいくつか紹介します:
データベースを読み取り専用で開きます:
>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE readonly(data)")
Traceback (most recent call last):
OperationalError: attempt to write a readonly database
まだ存在しない場合、新しいデータベース・ファイルを暗黙に作成しません。なお、新しいファイルが作成できない場合には
OperationalError
が送出されます:
>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file
共有の名前付きインメモリ・データベースを作成します:
db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
con1.execute("CREATE TABLE shared(data)")
con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)
con1.close()
con2.close()
パラメータのリストを含む、この機能の詳細については、 SQLite URI documentation を参照してください。
行工場(row factories)の作成方法と使用方法¶
デフォルトでは、 sqlite3
は各行(row)を タプル
として表します。 タプル
があなたのニーズと合わない場合は、 sqlite3.Row
クラスまたはカスタム row_factory
を使用できます。
row_factory
は Cursor
と Connection
の両方に属性として存在しますが、 その接続(connection)から作成されたすべてのカーソルが同一の行工場(row factory)を使用するようにするために、 Connection.row_factory
を設定することをお勧めします。
Row
は、 タプル
に対してメモリ・オーバーヘッドとパフォーマンスへの影響を最小限に抑えながら、列(row)へのインデックスによるアクセスと、列への(大文字と小文字を区別しない)名前によるアクセスを提供します。 Row
を行工場(row factory)として使用するには、 row_factory
属性に割り当てます:
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row
このように設定すると、クエリは Row
オブジェクトを返すようになります:
>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0] # Access by index.
'Earth'
>>> row["name"] # Access by name.
'Earth'
>>> row["RADIUS"] # Column names are case-insensitive.
6378
>>> con.close()
注釈
The FROM
clause can be omitted in the SELECT
statement, as in the
above example. In such cases, SQLite returns a single row with columns
defined by expressions, e.g. literals, with the given aliases
expr AS alias
.
各列名が各値にマップされた dict
として行を返す、カスタム row_factory
を作成することもできます:
def dict_factory(cursor, row):
fields = [column[0] for column in cursor.description]
return {key: value for key, value in zip(fields, row)}
これを使うと、クエリは タプル
の代わりに dict
を返すようになります:
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
... print(row)
{'a': 1, 'b': 2}
>>> con.close()
以下の行工場(row factory)は 名前付きタプル を返します:
from collections import namedtuple
def namedtuple_factory(cursor, row):
fields = [column[0] for column in cursor.description]
cls = namedtuple("Row", fields)
return cls._make(row)
namedtuple_factory()
は以下のようにして使う事ができます:
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0] # Indexed access.
1
>>> row.b # Attribute access.
2
>>> con.close()
上記レシピをチューニングすれば、 namedtuple
の代わりに dataclass
または、その他のカスタム・クラスを使用するように適合(adapt)させることができます。
How to handle non-UTF-8 text encodings¶
By default, sqlite3
uses str
to adapt SQLite values
with the TEXT
data type.
This works well for UTF-8 encoded text, but it might fail for other encodings
and invalid UTF-8.
You can use a custom text_factory
to handle such cases.
Because of SQLite's flexible typing, it is not uncommon to encounter table
columns with the TEXT
data type containing non-UTF-8 encodings,
or even arbitrary data.
To demonstrate, let's assume we have a database with ISO-8859-2 (Latin-2)
encoded text, for example a table of Czech-English dictionary entries.
Assuming we now have a Connection
instance con
connected to this database,
we can decode the Latin-2 encoded text using this text_factory
:
con.text_factory = lambda data: str(data, encoding="latin2")
For invalid UTF-8 or arbitrary data in stored in TEXT
table columns,
you can use the following technique, borrowed from the Unicode HOWTO:
con.text_factory = lambda data: str(data, errors="surrogateescape")
注釈
The sqlite3
module API does not support strings
containing surrogates.
説明¶
トランザクション制御¶
sqlite3
は、データベース・トランザクションを開くかどうか、いつ、どのように開くかを制御する複数の方法を提供します。 autocommit 属性に依るトランザクション制御 が推奨されますが、isolation_level 属性に依るトランザクション制御 は Python 3.12 より前の動作を保持します。
autocommit
属性に依るトランザクション制御¶
トランザクションの動作を制御する推奨方法は、 Connection.autocommit
属性を使用することです。 この属性は connect()
の autocommit パラメータを使用して設定して頂けるとありがたいです。
autocommit を False
に設定することをお勧めします。そうすると PEP 249 対応のトランザクション制御を行います。これは以下のことを意味します:
sqlite3
はトランザクションが常に開いていることを保証します。そのため、connect()
やConnection.commit()
やConnection.rollback()
は暗黙に新しいトランザクションを開きます(1つ目については保留中のトランザクションを閉じた直後で、後の2つについてはその直後に、です)。sqlite3
はトランザクションを開くときにBEGIN DEFERRED
文を使用します。トランザクションは、
commit()
を使用して明示的にコミットする必要があります。トランザクションは、
rollback()
を使用して明示的にロールバックする必要があります。データベースの保留中に行った変更は
close()
された場合、暗黙のロールバックが実行されます。
autocommit を True
に設定して、SQLite の autocommit mode を有効にします。このモードでは、 Connection.commit()
と Connection.rollback()
は効果がありません。 SQLite の自動コミット・モード(autocommit mode)は、 PEP 249 対応の Connection.autocommit
属性とは異なることに注意してください。 Connection.in_transaction
を使用して、低レベル SQLite 自動コミット・モードを問い合わせします。
autocommit を LEGACY_TRANSACTION_CONTROL
に設定して、トランザクション制御の振る舞いを Connection.isolation_level
属性に任せます。詳細については isolation_level 属性に依るトランザクション制御 を参照してください。
isolation_level
属性に依るトランザクション制御¶
注釈
推奨のトランザクション制御方法は、 autocommit
属性を使用することです。 autocommit 属性に依るトランザクション制御 を参照してください。
Connection.autocommit
が LEGACY_TRANSACTION_CONTROL
(これがデフォルトです)に設定されている場合、トランザクションの振る舞いは Connection.isolation_level
属性を使用して制御されます。 LEGACY_TRANSACTION_CONTROL
以外の場合、 isolation_level
は効果がありません。
接続属性 isolation_level
が None
で無いのなら、 execute()
や executemany()
が INSERT
または UPDATE
または DELETE
または REPLACE
文を実行する前に新しいトランザクションが暗黙に開かれます。それ以外のSQL文では暗黙のトランザクション処理は行われません。 commit()
メソッドや rollback()
メソッドを使用して、 保留中のトランザクションをそれぞれコミットおよびロールバックします。あなたは、背後にある SQLite ライブラリのトランザクションの振る舞い(SQLite transaction behaviour) — つまり、 sqlite3 が暗黙に実行する BEGIN
文の有無とその種類 – を、 isolation_level
属性を介して選択できます。
isolation_level
が None
に設定されていると、トランザクションは暗黙に開かれません。これにより、背後にある SQLite ライブラリを自動コミット・モード(autocommit mode)にしたまま、 明示的な SQL 文を使用して、 ユーザが独自のトランザクション処理を行えるようにします。背後にある SQLite ライブラリの自動コミット・モードは、 in_transaction
属性を使用して問い合わせできます。
executescript()
メソッドは、 isolation_level
の値に関係なく、与えられた SQL スクリプトの実行前に、保留中のトランザクションを暗黙にコミットします。
バージョン 3.6 で変更: sqlite3
は、 DDL文の前に、開いているトランザクションを暗黙にコミットしていました。これはもはや当てはまりません。
バージョン 3.12 で変更: 推奨のトランザクションを制御方法は、 autocommit
属性を使用することです。