"sqlite3" --- SQLite データベース用の DB-API 2.0 インターフェース
*****************************************************************

**ソースコード:** Lib/sqlite3/

SQLite は、軽量なディスク上のデータベースを提供する C ライブラリです。
別のサーバプロセスを用意する必要なく、 SQL クエリー言語の非標準的な一
種を使用してデータベースにアクセスできます。一部のアプリケーションは内
部データ保存に SQLite を使えます。また、SQLite を使ってアプリケーショ
ンのプロトタイプを作り、その後そのコードを PostgreSQL や Oracle のよう
な大規模データベースに移植するということも可能です。

"sqlite3" モジュールは Gerhard Häring が作成しました。 **PEP 249** に
記述された DB-API 2.0 仕様に準拠する SQL インターフェースを提供し、サ
ードパーティーの SQLite ライブラリを必要とします。

これは *オプションのモジュール* です。 お使いの CPython に含まれていな
い場合は、配布元 (Python を提供した人や組織) のドキュメントを確認して
ください。 配布する側の方は オプションのモジュールの要件 を参照してく
ださい。

この文書には大きく分けて 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)を含むデータベースの基
本概念を理解していることを前提としています。

まず、新しいデータベースを作り、"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',)

クエリがテーブル名を含む "tuple" を返すことから、テーブルが作成された
と分かります。 存在しないテーブル "spam" を "sqlite_master" に問い合わ
せると、"res.fetchone()" は "None" を返します:

   >>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
   >>> res.fetchone() is None
   True

再び "cur.execute(...)" を呼び出して "INSERT" 文を実行し、SQL リテラル
で指定した 2 行のデータを追加します。

   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 つの "tuple" の "リスト" で、 それぞれのタプルにその行の
"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()  # 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 データベース
を作成し、複数の方法でデータを挿入し、そこから値を取得することができる
ようになりました。

参考:

  * ハウツー・ガイド も参考にしてください:

    * プレースホルダを使用して SQL クエリに値を結び付ける方法

    * カスタム Python 型を SQLite 値に適合させる方法

    * SQLite 値をカスタム Python 型に変換する方法

    * 接続(connection)コンテキストマネージャの使い方

    * 行工場(row factories)の作成方法と使用方法

  * トランザクション制御 トランザクション制御の背景についてより深く掘
    り下げた説明。


リファレンス
============


モジュール関数
--------------

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*) -- 開くデータベースファイル
        のパスです。 "":memory:"" を渡すと、メモリ内にのみ存在する
        SQLite データベース を作成し、接続を開けます。

      * **timeout** (*float*) -- テーブルがロックされている場合、
        "OperationalError" を送出する前に接続を待機する秒数。 別の接続
        がテーブルを変更するためにトランザクションを開くと、そのテーブ
        ルはトランザクションがコミットされるまでロックされます。 デフ
        ォルトは 5 秒です。

      * **detect_types** (*int*) -- SQLite がネイティブにサポートして
        いないデータ型 を Python の型へ変換するために、
        "register_converter()" で登録された変換関数を検索するかどうか
        と、その方法を制御します。 有効にするには、"PARSE_DECLTYPES"
        と "PARSE_COLNAMES" のいずれか、または両方を "|" (ビット論理和
        ) で組み合わせて指定します。 両方のフラグを指定した場合は、宣
        言された型よりも列名を優先します。 デフォルト ("0") では型の検
        出は無効です。

      * **isolation_level** (*str** | **None*) -- 従来のトランザクショ
        ン処理の動作を制御します。 詳しくは
        "Connection.isolation_level" と isolation_level 属性に依るトラ
        ンザクション制御 を参照してください。 ""DEFERRED"" (デフォルト
        )、""EXCLUSIVE""、""IMMEDIATE"" のいずれかを指定できます。 ト
        ランザクションを暗黙に開始しないようにするには "None" を指定し
        ます。 "Connection.autocommit" が "LEGACY_TRANSACTION_CONTROL"
        (デフォルト) でなければ、効果はありません。

      * **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 (Uniform
        Resource Identifier) として解釈されます。 スキームの部分は
        ""file:"" でなければならず、パス(path)は相対パスまたは絶対パス
        にすることができます。 クエリ文字列により、 パラメーターを
        SQLite に渡すことができ、さまざまな SQLite URI の操作方法 が有
        効になります。

      * **autocommit** (*bool*) -- **PEP 249** に従うトランザクション
        処理の動作を制御します。 詳しくは "Connection.autocommit" と
        autocommit 属性に依るトランザクション制御 を参照してください。
        現在の *autocommit* のデフォルトは
        "LEGACY_TRANSACTION_CONTROL" です。 将来の Python リリースでは
        、デフォルトが "False" に変わります。

   戻り値の型:
      *Connection*

   引数 "database" を指定して 監査イベント "sqlite3.connect" を送出し
   ます。

   引数 "connection_handle" を指定して 監査イベント
   "sqlite3.connect/handle" を送出します。

   バージョン 3.4 で変更: "uri" パラメータが追加されました。

   バージョン 3.7 で変更: *database* は、文字列だけでなく、 *path-like
   object* にすることもできるようになりました。

   バージョン 3.10 で変更: 監査イベント "sqlite3.connect/handle" が追
   加されました。

   バージョン 3.12 で変更: *autocommit* 引数が追加されました。

   バージョン 3.15 で変更: *database* 以外のすべての引数がキーワード専
   用になりました。

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" を使用します。

   注釈:

     ユーザー定義関数のコールバックで発生したエラーは、送出できない例
     外として記録されます。 失敗したコールバックの情報を調べるには、"
     送出できない例外のフックハンドラー" を使ってください。

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_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" と
   組み合わせることができます。

   注釈:

     Generated fields (for example "MAX(p)") are returned as "str".
     Use "PARSE_COLNAMES" to enforce types for such queries.

sqlite3.PARSE_COLNAMES

   このフラグ値を "connect()" の *detect_types* 引数に渡すと、クエリの
   列名から型名を読み取り、それを変換関数の辞書のキーとして変換関数を
   検索します。 クエリの列名はダブルクォート (""") で囲み、型名は角括
   弧 ("[]") で囲む必要があります。

      SELECT MAX(p) as "p [point]" FROM test;  ! will look up converter "point"

   このフラグは "|" (ビット論理和)演算子を使用して "PARSE_DECLTYPES"
   と組み合わせることができます。

sqlite3.SQLITE_OK
sqlite3.SQLITE_DENY
sqlite3.SQLITE_IGNORE

   "Connection.set_authorizer()" に渡す *呼び出し可能オブジェクト*
   *authorizer_callback* が返すフラグで、次のいずれかを示します:

   * アクセスは許可されました("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.sqlite_version

   "文字列" としての、ランタイム SQLite ライブラリのバージョン番号。

sqlite3.sqlite_version_info

   "整数" の "タプル" としての、ランタイム SQLite ライブラリのバージョ
   ン番号。

sqlite3.SQLITE_KEYWORDS

   SQLite のすべてのキーワードを含む "tuple" です。

   この定数は、Python が SQLite 3.24.0 以降でコンパイルされている場合
   にのみ利用できます。

   Added in version 3.15.

sqlite3.threadsafety

   "sqlite3" モジュールがサポートするスレッドセーフのレベルを示す、DB-
   API 2.0 で必要な整数定数。 この属性は、背後の SQLite ライブラリのコ
   ンパイル時のデフォルトの SQLite スレッド・モード (threading mode)に
   基づいて設定されます。 SQLite のスレッド・モードは以下のとおりです:

   1. **シングル・スレッド**: このモードでは、すべてのミューテックスが
      無効になり、一度に複数のスレッドで SQLite を使用するのは安全では
      ありません。

   2. **マルチ・スレッド**: このモードでは、 1 つのデータベース接続が
      2 つ以上のスレッドで同時に使用されない限り、複数のスレッドで
      SQLite を安全に使用できます。

   3. **直列化**: 直列化(serialized)モードでは、 SQLite を複数のスレッ
      ドで制限なく安全に使用できます。

   SQLite スレッド・モードと、 DB-API 2.0 のスレッドセーフ・レベルとの
   対応は以下のとおりです:

   +--------------------+------------------------+------------------------+---------------------------------+
   | SQLite スレッド・  | **threadsafety**       | SQLITE_THREADSAFE      | DB-API 2.0 での意味             |
   | モード             |                        |                        |                                 |
   |====================|========================|========================|=================================|
   | シングル・スレッド | 0                      | 0                      | スレッドはモジュールを共有でき  |
   |                    |                        |                        | ません                          |
   +--------------------+------------------------+------------------------+---------------------------------+
   | マルチ・スレッド   | 1                      | 2                      | スレッドはモジュールを共有でき  |
   |                    |                        |                        | ますが、接続は共有できません    |
   +--------------------+------------------------+------------------------+---------------------------------+
   | 直列化             | 3                      | 1                      | スレッドは、モジュールや接続や  |
   |                    |                        |                        | カーソルを共有できます          |
   +--------------------+------------------------+------------------------+---------------------------------+

   バージョン 3.11 で変更: "1" とハード・コーディングする代わりに
   *threadsafety* を動的に設定します。

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 のドキュメント: データベース接続の設定オプション

バージョン 3.12 で非推奨、バージョン 3.14 で削除: "version" 定数と
"version_info" 定数。


Connection オブジェクト
-----------------------

class sqlite3.Connection

   開いた SQLite データベースの各々は、 "sqlite3.connect()" を使用して
   作成される "Connection" オブジェクトによって表されます。
   "Connection" オブジェクトの主な目的は "Cursor" オブジェクトの作成と
   トランザクション制御 です。

   参考:

     * 接続(connection)ショートカット・メソッドの使い方

     * 接続(connection)コンテキストマネージャの使い方

   バージョン 3.13 で変更: "Connection" オブジェクトが削除される前に
   "close()" が呼び出されていないと、"ResourceWarning" を出すようにな
   りました。

   SQLite データベース接続(connection)には、以下の属性とメソッドがあり
   ます:

   cursor(factory=Cursor)

      "Cursor" オブジェクトを作成して返します。 cursor メソッドは、単
      一のオプション・パラメーター *factory* を受け入れます。
      *factory* を指定する場合、これは "Cursor" またはそのサブクラスの
      インスタンスを返す *呼び出し可能オブジェクト* である必要がありま
      す。

   blobopen(table, column, rowid, /, *, readonly=False, name='main')

      既存の BLOB (Binary Large OBject) への "Blob" ハンドルを開きます
      。

      パラメータ:
         * **table** (*str*) -- 当該 BLOB が配置されているテーブルの名
           前。

         * **column** (*str*) -- 当該 BLOB が配置されている列(column)
           の名前。

         * **rowid** (*int*) -- BLOB がある行の ID。

         * **readonly** (*bool*) -- 書き込み権限なしで BLOB を開く必要
           がある場合は、 "True" に設定します。 デフォルトは "False"
           です。

         * **name** (*str*) -- 当該 BLOB が配置されているデータベース
           名。 デフォルトは ""main"" です。

      例外:
         **OperationalError** -- "WITHOUT ROWID" テーブルで BLOB を開
         こうとしたとき。

      戻り値の型:
         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 で変更: *deterministic* 引数が追加されました。

      バージョン 3.15 で変更: 最初の 3 つの引数が位置専用になりました
      。

      例:

         >>> 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()

   create_aggregate(name, n_arg, aggregate_class, /)

      ユーザ定義集計関数を作成または削除します。

      パラメータ:
         * **name** (*str*) -- SQL 集計関数の名前。

         * **n_arg** (*int*) -- SQL 集計関数が受け入れることができる引
           数の数。 "-1" を指定すると、任意の数の引数を取ることができ
           ます。

         * **aggregate_class** (*class* | None) -- 次のメソッドを実装
           するクラスです。 "step()" は行を集計に加えます。
           "finalize()" は集計の最終結果を SQLite がネイティブにサポー
           トする型 で返します。 "step()" メソッドが受け取る引数の数は
           *n_arg* で指定します。 既存の SQL 集計関数を削除するには
           "None" を指定します。

      バージョン 3.15 で変更: 3 つの引数がすべて位置専用になりました。

      例:

         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()

   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.

      例:

         # https://www.sqlite.org/windowfunctions.html#udfwinfunc から引用した例
         class WindowSumInt:
             def __init__(self):
                 self.count = 0

             def step(self, value):
                 """現在のウィンドウに行を加える。"""
                 self.count += value

             def value(self):
                 """集計の現在の値を返す。"""
                 return self.count

             def inverse(self, value):
                 """現在のウィンドウから行を取り除く。"""
                 self.count -= value

             def finalize(self):
                 """集計の最終的な値を返す。

                 必要なクリーンアップ処理はここに書く。
                 """
                 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.15 で変更: 唯一の引数が位置専用になりました。

   set_progress_handler(progress_handler, /, n)

      SQLite 仮想マシンの命令を *n* 個実行するごとに呼び出されるように
      、 *呼び出し可能オブジェクト* *progress_handler* を登録します。
      これは、 GUI の更新など、長時間実行される操作中に SQLite から呼
      び出されるようにしたい場合に便利です。

      以前にインストールした progress ハンドラーをクリアしたい場合は、
      *progress_handler* に "None" を指定してメソッドを呼び出します。

      ハンドラー関数からゼロ以外の値を返すと、現在実行中のクエリを終了
      (terminate)し、 "DatabaseError" 例外を送出します。

      バージョン 3.15 で変更: 第1引数は位置専用になりました。

   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.15 で変更: 第1引数は位置専用になりました。

   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)

         # 全文検索拡張機能を読み込む
         con.execute("select load_extension('./fts3.so')")

         # または API 呼び出しで拡張機能を読み込むこともできる:
         # con.load_extension("./fts3.so")

         # 拡張機能の読み込みを再び無効にする
         con.enable_load_extension(False)

         # 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 で変更: *entrypoint* 引数が追加されました。

   iterdump(*, filter=None)

      データベースを SQL ソース・コードとしてダンプする *iterator* を
      返します。 後で復元するためにメモリ内データベースを保存する場合
      に便利です。 **sqlite3** シェルの ".dump" コマンドに似ています。

      パラメータ:
         **filter** (*str** | **None*) -- ダンプするデータベースオブジ
         ェクトを選ぶ、省略可能な "LIKE" パターンです。 例えば
         "prefix_%" です。 "None" (デフォルト) の場合は、すべてのデー
         タベースオブジェクトを含めます。

      例:

         # ファイル example.db を SQL ダンプファイル 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()

      参考: UTF-8 以外のテキストエンコーディングの扱い方

      バージョン 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.

      参考: UTF-8 以外のテキストエンコーディングの扱い方

   getlimit(category, /)

      接続(connection)の実行時制限を取得します。

      パラメータ:
         **category** (*int*) -- 問い合わせを行う実行時制限カテゴリー
         (SQLite limit category)。

      戻り値の型:
         int

      例外:
         **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*) -- 新しい制限の値。 負数の場合、 現在の制
           限は変更されません。

      戻り値の型:
         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 を指定します。

      戻り値の型:
         bool

      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" データベースの場合、 直列化は、 そのデータベースがディス
      クにバックアップされた場合にディスクに書き込まれるバイト・シーケ
      ンスと同じです。

      パラメータ:
         **name** (*str*) -- 直列化するデータベース名。 デフォルトは
         ""main"" です。

      戻り値の型:
         bytes

      注釈:

        このメソッドは、 背後の SQLite ライブラリに直列化 API がある場
        合にのみ使用できます。

      Added in version 3.11.

   deserialize(data, /, *, name='main')

      "直列化" されたデータベースを "Connection" に、 脱直列化
      (deserialize)します。 このメソッドにより、 データベース接続はデ
      ータベース *name* から切断され、そして、  *data* に含まれる直列
      化データに基づいて、 データベース *name* がインメモリ・データベ
      ースとして再度開かれます。

      パラメータ:
         * **data** (*bytes*) -- 直列化されたデータベース。

         * **name** (*str*) -- 脱直列化(deserialize)したデータを入れる
           データベース名。 デフォルトは ""main"" です。

      例外:
         * **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)の作成方法と使用方法 をご覧下さい。

      バージョン 3.15 で変更: "row_factory" 属性を削除できなくなりまし
      た。

   text_factory

      "bytes" のパラメータを受け取り、そのテキスト表現を返す *呼び出し
      可能オブジェクト* です。呼び出し可能オブジェクトは "TEXT" データ
      型である SQLite 値に対して呼び出されます。 デフォルトでは、 この
      属性は "str" に設定されています。

      詳しくは UTF-8 以外のテキストエンコーディングの扱い方 を参照して
      ください。

      バージョン 3.15 で変更: "text_factory" 属性を削除できなくなりま
      した。

   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=(), /)

      単一の SQL 文を実行します。 プレースホルダー を使って Python の
      値をバインドすることもできます。

      パラメータ:
         * **sql** (*str*) -- 単一の SQL 文。

         * **parameters** ("dict" | *sequence*) -- *sql* のプレースホ
           ルダに結び付け(bind)する Python 値。 名前付きプレースホルダ
           が使用されている場合は "dict" です。 名前のないプレースホル
           ダが使用されている場合は *sequence* です。 プレースホルダを
           使用して SQL クエリに値を結び付ける方法 を参照してください
           。

      例外:
         **ProgrammingError** -- *sql* に複数の SQL 文が含まれている場
         合。 名前付きプレースホルダー を使っているのに、*parameters*
         が "dict" ではなくシーケンスの場合。

      "autocommit" が "LEGACY_TRANSACTION_CONTROL" で、かつ、
      "isolation_level" が "None" で無く、 かつ、 *sql* が "INSERT" ま
      たは "UPDATE" または "DELETE" または "REPLACE" 文で、かつ、開い
      ているトランザクションがない場合、 *sql* を実行する前にトランザ
      クションが暗黙に開かれます。

      バージョン 3.14 で変更: 名前付きプレースホルダー を使っているの
      に、*parameters* が "dict" ではなくシーケンスの場合は、
      "ProgrammingError" を送出するようになりました。

      複数の SQL 文を実行するには "executescript()" を使用します。

   executemany(sql, parameters, /)

      *parameters* のすべての item に対して、 パラメーター化 された
      DML (Data Manipulation Language) SQL 文である *sql* を繰り返し実
      行します。

      "execute()" と同一の暗黙のトランザクション処理を使用します。

      パラメータ:
         * **sql** (*str*) -- 単一の DML 文。

         * **parameters** (*iterable*) -- *sql* のプレースホルダに結び
           付け(bind)するためのパラメータの *iterable* 。 プレースホル
           ダを使用して SQL クエリに値を結び付ける方法 参照。

      例外:
         **ProgrammingError** -- *sql* に複数の SQL 文が含まれている場
         合、または DML 文でない場合。 名前付きプレースホルダー を使っ
         ているのに、*parameters* の各要素が "dict" ではなくシーケンス
         の場合。

      例:

         rows = [
             ("row1",),
             ("row2",),
         ]
         # cur は sqlite3.Cursor オブジェクト
         cur.executemany("INSERT INTO data VALUES(?)", rows)

      注釈:

        RETURNING 句(RETURNING clauses)を含むDML文を含め、結果の行はす
        べて破棄されます。

      バージョン 3.14 で変更: 名前付きプレースホルダー を使っているの
      に、*parameters* の各要素が "dict" ではなくシーケンスの場合は、
      "ProgrammingError" を送出するようになりました。

   executescript(sql_script, /)

      *sql_script* 内の複数のSQL文を実行します。 "autocommit" が
      "LEGACY_TRANSACTION_CONTROL" で、かつ、保留中のトランザクション
      がある場合、暗黙の "COMMIT" 文が最初に実行されます。その他の暗黙
      のトランザクション制御は実行されませんので、トランザクション制御
      を *sql_script* に追加しなければなりません。

      *sql_script* は "文字列" でなければなりません。

      例:

         # cur は sqlite3.Cursor オブジェクト
         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" の場合、 クエリ結果セットの次の 1 行を "
      タプル" として返します。 それ以外の場合は、 それを行工場(row
      factory)に渡し、 その結果を返します。 これ以上データが無い場合は
      "None" を返します。

   fetchmany(size=cursor.arraysize)

      クエリ結果の次の行セットを "list" として返します。行がそれ以上な
      い場合は、空のリストを返します。

      呼び出しごとに取得する行数は、*size* パラメーターで指定されます
      。 *size* が指定されていない場合、 "arraysize" が取得する行数を
      決定します。有効な行の数が *size* 未満の場合は、有効な数の行が返
      されます。

      *size* 引数とパフォーマンスの関係についての注意です。パフォーマ
      ンスを最適化するためには、大抵、 arraysize 属性を利用するのがベ
      ストです。 *size* 引数を利用したのであれば、次回の "fetchmany()"
      の呼び出しでも *size* 引数に同一の値を指定するのがのがベストです
      。

      バージョン 3.15 で変更: *size* に負の値を指定すると、
      "ValueError" を送出して拒否するようになりました。

   fetchall()

      クエリ結果の(残りの)すべての行を "list" として返します。 有効な
      行がない場合は、空のリストを返します。 "arraysize" 属性は、この
      操作のパフォーマンスに影響を与える可能性があることに注意してくだ
      さい。

   close()

      ("__del__" が呼び出される時ではなく、) 今すぐカーソルを閉じます
      。

      この時点から、このカーソルは使用できなくなります。今後、このカー
      ソルで何らかの操作を試みると、 "ProgrammingError" 例外が送出され
      ます。

   setinputsizes(sizes, /)

      DB-API で必要です。 "sqlite3" では何もしません。

   setoutputsize(size, column=None, /)

      DB-API で必要です。 "sqlite3" では何もしません。

   arraysize

      "fetchmany()" によって返される行(row)数を制御する、読み取りと書
      き込みが可能な属性。 デフォルト値は 1 で、これは呼び出しごとに 1
      行が取得されることを意味します。

      バージョン 3.15 で変更: 負の値を指定すると、"ValueError" を送出
      して拒否するようになりました。

   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 (Common Table Expression) クエリを含む
      、ほかの文では "-1" になります。 "execute()" メソッドと
      "executemany()" メソッドによってのみ、文の実行が完了した後に更新
      されます。 そのため、"rowcount" が更新されるには、結果の行があれ
      ばそれを取得する必要があります。

   row_factory

      この "Cursor" から取得された行の表現方法を制御します。 "None" の
      場合、行は "タプル" として表されます。 "sqlite3.Row" に設定する
      こともできます。 そしてまた、 "Cursor" オブジェクトと、 行の値の
      "tuple" の、 2 つの引数を受け取り、 SQLite の行(row)を表すカスタ
      ム・オブジェクトを返す、 *呼び出し可能オブジェクト* に設定するこ
      ともできます。

      "Cursor" オブジェクト の作成時に "Connection.row_factory" の値を
      この属性のデフォルト値として設定します。 この属性に割り当てても
      、親接続(parent connection)の "Connection.row_factory" には影響
      しません。

      詳細は 行工場(row factories)の作成方法と使用方法 をご覧下さい。

      バージョン 3.15 で変更: "row_factory" 属性を削除できなくなりまし
      た。


Row オブジェクト
----------------

class sqlite3.Row

   "Row" インスタンスは、 "Connection" オブジェクトの、高度に最適化さ
   れた "row_factory" の役割をします。 反復(iteration)や、等しいかどう
   かのテスト(equality testing)や、 "len()" 関数や 、 列名(column
   name)とインデックスによる *マッピング* のアクセスを、サポートします
   。

   列名(column names)と値(values)が全く同一である 2 つの "Row"  オブジ
   ェクトを比較すると、等しいと見なされます。

   詳細は 行工場(row factories)の作成方法と使用方法 をご覧下さい。

   keys()

      "文字列" で表した列名の "リスト" を返します。 クエリの直後では、
      列名は "Cursor.description" の各タプルの最初の要素です。

   バージョン 3.5 で変更: スライスがサポートされました。


Blob オブジェクト
-----------------

class sqlite3.Blob

   Added in version 3.11.

   "Blob" インスタンスは、 SQLite の BLOB (Binary Large OBject) とデー
   タを読み書きできる *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))")

      # 2 回の書き込み操作で BLOB に書き込む:
      with con.blobopen("test", "blob_col", 1) as blob:
          blob.write(b"hello, ")
          blob.write(b"world.")
          # BLOB の最初と最後のバイトを変更する
          blob[0] = ord("H")
          blob[-1] = ord("!")

      # BLOB の内容を読み取る
      with con.blobopen("test", "blob_col", 1) as blob:
          greeting = blob.read()

      print(greeting)  # "b'Hello, world!'" を出力する
      con.close()

   close()

      Blob を閉じます。

      この時点から、 BLOB は使用できなくなります。 BLOB に対してさらに
      操作を試みると、 "Error" (またはそのサブクラスの) 例外を送出しま
      す。

   read(length=-1, /)

      現在のオフセット位置から BLOB のデータを *length* バイト読み取り
      ます。 BLOB の末尾に達した場合は、EOF (End of File) までのデータ
      を返します。 *length* を省略した場合や負の値を指定した場合、
      "read()" は BLOB の末尾まで読み取ります。

   write(data, /)

      BLOB の現在のオフセット位置から *data* を書き込みます。 この関数
      では BLOB の長さを変更できません。 BLOB の末尾を超えて書き込もう
      とすると "ValueError" を送出します。

   tell()

      BLOBの現在のオフセット位置(current access position)を返します。

   seek(offset, origin=os.SEEK_SET, /)

      BLOB の現在のアクセス位置を *offset* に設定します。 *origin* 引
      数のデフォルトは "os.SEEK_SET" (BLOB 内の絶対位置) です。
      *origin* のほかの値は "os.SEEK_CUR" (現在位置からの相対移動) と
      "os.SEEK_END" (BLOB の末尾からの相対移動) です。


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 の型   |
|=================================|===============|
| "None"                          | "NULL"        |
+---------------------------------+---------------+
| "int"                           | "INTEGER"     |
+---------------------------------+---------------+
| "float"                         | "REAL"        |
+---------------------------------+---------------+
| "str"                           | "TEXT"        |
+---------------------------------+---------------+
| "bytes"                         | "BLOB"        |
+---------------------------------+---------------+

SQLite の型から Python の型へのデフォルトでの変換は以下の通りです:

+---------------+------------------------------------------------+
| SQLite の型   | Python の型                                    |
|===============|================================================|
| "NULL"        | "None"                                         |
+---------------+------------------------------------------------+
| "INTEGER"     | "int"                                          |
+---------------+------------------------------------------------+
| "REAL"        | "float"                                        |
+---------------+------------------------------------------------+
| "TEXT"        | "text_factory" に依存する。デフォルトでは      |
|               | "str" 。                                       |
+---------------+------------------------------------------------+
| "BLOB"        | "bytes"                                        |
+---------------+------------------------------------------------+

"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" を挿入
してすべての行を選択できます:

   >>> # 危険なので、このようにしてはいけない!
   >>> 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)")

   # 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)

   # SELECT クエリで qmark スタイルを使う:
   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)

   # 適合関数と変換関数を登録する
   sqlite3.register_adapter(Point, adapt_point)
   sqlite3.register_converter("point", convert_point)

   # 1) 宣言された型を使って解析する
   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) 列名を使って解析する
   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 as dt
   import sqlite3

   def adapt_date_iso(val):
       """datetime.date を ISO 8601 の日付に適合させる。"""
       return val.isoformat()

   def adapt_datetime_iso(val):
       """datetime.datetime をタイムゾーン情報のない ISO 8601 の日付に適合させる。"""
       return val.replace(tzinfo=None).isoformat()

   def adapt_datetime_epoch(val):
       """datetime.datetime を Unix タイムスタンプに適合させる。"""
       return int(val.timestamp())

   sqlite3.register_adapter(dt.date, adapt_date_iso)
   sqlite3.register_adapter(dt.datetime, adapt_datetime_iso)
   sqlite3.register_adapter(dt.datetime, adapt_datetime_epoch)

   def convert_date(val):
       """ISO 8601 の日付を datetime.date オブジェクトに変換する。"""
       return dt.date.fromisoformat(val.decode())

   def convert_datetime(val):
       """ISO 8601 の日時を datetime.datetime オブジェクトに変換する。"""
       return dt.datetime.fromisoformat(val.decode())

   def convert_timestamp(val):
       """Unix エポックを基準とするタイムスタンプを datetime.datetime オブジェクトに変換する。"""
       return dt.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" オブジェクトに対す
る呼び出し一つで行なえます。

   # テーブルを作成してデータを入れる。
   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)

   # テーブルの内容を表示する
   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() はショートカットメソッドではなく、自動では呼び出されない。
   # 接続オブジェクトは手動で閉じる必要がある。
   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)")

   # 成功すると、後で con.commit() が自動的に呼び出される
   with con:
       con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

   # with ブロックが例外で終了すると、その後に con.rollback() が呼び出される。
   # 例外は引き続き送出されるため、捕捉する必要がある。
   try:
       with con:
           con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
   except sqlite3.IntegrityError:
       print("couldn't add Python twice")

   # 接続オブジェクトをコンテキストマネージャーとして使っても、
   # トランザクションのコミットやロールバックだけなので、接続は手動で閉じる。
   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
   >>> con.close()

* まだ存在しない場合、新しいデータベース・ファイルを暗黙に作成しません
  。なお、新しいファイルが作成できない場合には "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)を "タプル" として表します。
"tuple" があなたのニーズと合わない場合は、 "sqlite3.Row" クラスまたは
カスタム "row_factory" を使用できます。

"row_factory" は "Cursor" と "Connection" の両方に属性として存在します
が、 その接続(connection)から作成されたすべてのカーソルが同一の行工場
(row factory)を使用するようにするために、 "Connection.row_factory" を
設定することをお勧めします。

"Row" は、 "tuple" に対してメモリ・オーバーヘッドとパフォーマンスへの
影響を最小限に抑えながら、列へのインデックスによるアクセスと、列への(
大文字と小文字を区別しない)名前によるアクセスを提供します。 "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]         # インデックスによるアクセス。
   'Earth'
   >>> row["name"]    # 名前によるアクセス。
   'Earth'
   >>> row["RADIUS"]  # 列名は大文字・小文字を区別しない。
   6378
   >>> con.close()

注釈:

  上の例のように、"SELECT" 文では "FROM" 句を省略できます。 その場合、
  SQLite は、リテラルなどの式で列を定義した 1 行を返し、"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)}

これを使うと、クエリは "tuple" の代わりに "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]  # インデックスによるアクセス。
   1
   >>> row.b   # 属性によるアクセス。
   2
   >>> con.close()

上記レシピをチューニングすれば、 "namedtuple" の代わりに "dataclass"
または、その他のカスタム・クラスを使用するように適合(adapt)させること
ができます。


UTF-8 以外のテキストエンコーディングの扱い方
--------------------------------------------

デフォルトでは、"sqlite3" は "str" を使って SQLite の "TEXT" 型の値を
変換します。 これは UTF-8 エンコードされたテキストには適していますが、
ほかのエンコーディングや不正な UTF-8 では失敗することがあります。 その
ような場合には、独自の "text_factory" を使えます。

SQLite の flexible typing により、"TEXT" 型のテーブル列に UTF-8 以外で
エンコードされたテキストや、任意のデータが含まれていることも珍しくあり
ません。 例えば、チェコ語・英語辞書の項目を格納するテーブルなど、
ISO-8859-2 (Latin-2) でエンコードされたテキストを持つデータベースがあ
るとします。 そのデータベースに接続した "Connection" インスタンス
"con" があれば、次の "text_factory" を使って Latin-2 のテキストをデコ
ードできます:

   con.text_factory = lambda data: str(data, encoding="latin2")

"TEXT" 型のテーブル列に格納された不正な UTF-8 や任意のデータには、
Unicode HOWTO で紹介している次の方法を使えます:

   con.text_factory = lambda data: str(data, errors="surrogateescape")

注釈:

  "sqlite3" モジュールの API は、サロゲートを含む文字列をサポートして
  いません。

参考: Unicode HOWTO


説明
====


トランザクション制御
--------------------

"sqlite3" は、データベース・トランザクションを開閉するかどうか、いつ、
どのように開閉するかを制御する複数の方法を提供します。 autocommit 属性
に依るトランザクション制御 が推奨されますが、isolation_level 属性に依
るトランザクション制御 は Python 3.12 より前の動作を保持します。


"autocommit" 属性に依るトランザクション制御
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

トランザクションの動作は "Connection.autocommit" 属性で制御することを
推奨します。 この属性は、できれば "connect()" の *autocommit* 引数で設
定してください。

*autocommit* を "False" に設定することをお勧めします。そうすると **PEP
249** 対応のトランザクション制御を行います。これは以下のことを意味しま
す:

* "sqlite3" はトランザクションが常に開いていることを保証します。 その
  ため、 "connect()" や "Connection.commit()" や
  "Connection.rollback()" は暗黙に新しいトランザクションを開きます(後
  者 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" 属性を使用することです。
