"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 3.7.15 以降が必要です。

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

First, we need to create a new database and open a database connection
to allow "sqlite3" to work with it. Call "sqlite3.connect()" to create
a connection to the database "tutorial.db" in the current working
directory, implicitly creating it if it does not exist:

   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',)

クエリがテーブルの名前を含む "タプル" を返すので、テーブルが作成された
ことがわかります。 存在しないテーブル "spam" に対して "sqlite_master"
をクエリすると、 "res.fetchone()" は "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

これで、あなたは、 "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=100, uri=False)

   SQLite データベースとの接続(connection)を開きます。

   パラメータ:
      * **database** (*path-like object*) -- 開きたいデータベース・フ
        ァイルへのファイル・パス。 ディスク上ではなく RAM 上に置くデー
        タベースへの接続を開くには、"":memory:"" を渡します。

      * **timeout** (*float*) -- How many seconds the connection
        should wait before raising an "OperationalError" when a table
        is locked. If another connection opens a transaction to modify
        a table, that table will be locked until the transaction is
        committed. Default five seconds.

      * **detect_types** (*int*) -- "register_converter()" で登録され
        た変換関数を使用して、 SQLite でネイティブにサポートされている
        型 以外のデータ型を検出して、 Python 型に変換するかどうか、そ
        して、その変換方法を制御します。 これは、 "PARSE_DECLTYPES" と
        "PARSE_COLNAMES" を(ビット論理和 "|" を使用して)任意の組み合わ
        せで設定することで有効になります。 両方のフラグが設定されてい
        る場合、宣言された型よりも列名が優先されます。 *detect_types*
        パラメータが設定されている場合でも、 生成されたフィールド(たと
        えば "max(data)")の型は検出できず、代わりに "str" が返されます
        。デフォルト ("0") では、データ型検出は無効になっています。

      * **isolation_level** (*str | None*) -- 接続(connection)の
        "isolation_level" は、 トランザクションが暗黙に開かれるかどう
        かと、どのように開かれるかを制御し、その値は ""DEFERRED"" (こ
        れがデフォルトです)または ""EXCLUSIVE"" または ""IMMEDIATE""
        のいずれか、または、トランザクションを暗黙に開くことができなく
        なる "None" です。詳細は トランザクション制御 を参照してくださ
        い。

      * **check_same_thread** (*bool*) -- If "True" (default),
        "ProgrammingError" will be raised if the database connection
        is used by a thread other than the one that created it. If
        "False", the connection may be accessed in multiple threads;
        write operations may need to be serialized by the user to
        avoid data corruption. See "threadsafety" for more
        information.

      * **factory** (*Connection*) -- デフォルトの "Connection" クラス
        でない場合に接続(connection)を作成する "Connection" のカスタム
        ・サブクラスです。

      * **cached_statements** (*int*) -- The number of statements that
        "sqlite3" should internally cache for this connection, to
        avoid parsing overhead. By default, 100 statements.

      * **uri** (*bool*) -- "True" に設定すると、 *database* は、ファ
        イル・パス(path)とオプションのクエリ文字列を含む URI (Uniform
        Resource Identifier) として解釈されます。 スキームの部分は
        ""file:"" でなければならず、パス(path)は相対パスまたは絶対パス
        にすることができます。 クエリ文字列により、 パラメーターを
        SQLite に渡すことができ、さまざまな SQLite URI の操作方法 が有
        効になります。

   戻り値の型:
      Connection

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

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

   バージョン 3.4 で追加: *uri* パラメーター。

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

   バージョン 3.10 で追加: 監査イベント "sqlite3.connect/handle"

sqlite3.complete_statement(statement)

   文字列 *statement* が 1 つ以上の完全な SQL 文を含んでいるように見え
   る場合、 "True" を返します。 閉じられていない文字列リテラルがないこ
   とと、文がセミコロンで終了していることを確認する以外の、構文の検証
   やパースは行われません。

   例えば:

      >>> sqlite3.complete_statement("SELECT foo FROM bar;")
      True
      >>> sqlite3.complete_statement("SELECT foo")
      False

   この関数は、コマンドライン入力時に便利で、入力されたテキストが完全
   な SQL 文を形成しているように見えるかどうか、または "execute()" を
   呼び出す前に追加の入力が必要かどうかを判断するのに使えます。

sqlite3.enable_callback_tracebacks(flag, /)

   Enable or disable callback tracebacks. By default you will not get
   any tracebacks in user-defined functions, aggregates, converters,
   authorizer callbacks etc. If you want to debug them, you can call
   this function with *flag* set to "True". Afterwards, you will get
   tracebacks from callbacks on "sys.stderr". Use "False" to disable
   the feature again.

sqlite3.register_adapter(type, adapter, /)

   Python の型 *type* を SQLite 型に適合させるための *adapter* 呼び出
   し可能オブジェクトを登録します。 適合関数(adapter)は、 *type* 型の
   Python オブジェクトを唯一の引数として呼び出され、 SQLite がネイティ
   ブに理解できる型 の値を返す必要があります。

sqlite3.register_converter(typename, converter, /)

   *typename* 型の SQLite オブジェクトを特定の型の Python オブジェクト
   に変換するための *converter* 呼び出し可能オブジェクトを登録します。
   変換関数(converter)は、 *typename* 型のすべての SQLite 値に対して呼
   び出されます。 変換関数には "bytes" オブジェクトが渡され、目的の
   Python の型のオブジェクトを返す必要があります。 SQLite のデータ型検
   出がどのように機能するかについては、 "connect()" の *detect_types*
   パラメータを参照してください。

   注釈: *typename* とクエリ内の型の名前は、大文字小文字を区別せずにマ
   ッチングされます。


モジュール定数
--------------

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()" に渡された *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"" とハー
   ドコーディングされています。

   注釈:

     The "named" DB-API parameter style is also supported.

sqlite3.sqlite_version

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

sqlite3.sqlite_version_info

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

sqlite3.threadsafety

   Integer constant required by the DB-API, stating the level of
   thread safety the "sqlite3" module supports. Currently hard-coded
   to "1", meaning *"Threads may share the module, but not
   connections."* However, this may not always be true. You can check
   the underlying SQLite library's compile-time threaded mode using
   the following query:

      import sqlite3
      con = sqlite3.connect(":memory:")
      con.execute("""
          select * from pragma_compile_options
          where compile_options like 'THREADSAFE=%'
      """).fetchall()

   Note that the SQLITE_THREADSAFE levels do not match the DB-API 2.0
   "threadsafety" levels.

sqlite3.version

   "文字列" としての、このモジュールのバージョン番号。これは SQLite ラ
   イブラリのバージョン番号ではありません。

sqlite3.version_info

   "整数" の "タプル" としての、このモジュールのバージョン番号。これは
   SQLite ライブラリのバージョン番号ではありません。


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

class sqlite3.Connection

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

   参考:

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

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

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

   cursor(factory=Cursor)

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

   commit()

      保留中のトランザクションをデータベースにコミットします。 開いて
      いるトランザクションがない場合、このメソッドは何もしません。

   rollback()

      保留中のトランザクションの開始点までロールバックします。開いてい
      るトランザクションがない場合、このメソッドは何もしません。

   close()

      データベース接続を閉じます。 保留中のトランザクションは暗黙にコ
      ミットされません。 保留中の変更が失われないように、データベース
      接続を閉じる前に必ず "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 が追加の最適化を実行できる
           ようになります。

      例外:
         **NotSupportedError** -- *deterministic* が 3.8.3 より古い
         SQLite バージョンで使用されている場合に送出されます。

      バージョン 3.8 で追加: *deterministic* パラメーター。

      例:

         >>> 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',)

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

   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" に設定します。

   interrupt()

      Call this method from a different thread to abort any queries
      that might be executing on the connection. Aborted queries will
      raise an "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" モジュールで利用できます。

   set_progress_handler(progress_handler, n)

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

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

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

   set_trace_callback(trace_callback)

      SQLite バックエンドによって実際に実行される各 SQL 文に対して呼び
      出される、呼び出し可能オブジェクトの *trace_callback* を登録しま
      す。

      コールバックに渡される唯一の引数は、("str" として渡される)実行中
      のSQL文です。 コールバックの戻り値は無視されます。 バックエンド
      は、 "Cursor.execute()" メソッドに渡されたSQL文を実行するだけで
      はないことに注意してください。 "sqlite3" モジュールの トランザク
      ション管理 や、現在のデータベース内で定義されたトリガーの実行そ
      の他も行います。

      *trace_callback* として "None" を渡すと、トレース・コールバック
      が無効になります。

      注釈:

        トレース・コールバックで送出した例外は伝播されません。 開発お
        よびデバッグの補助として、 "enable_callback_tracebacks()" を使
        用して、トレース・コールバックで送出した例外からのトレースバッ
        クの出力を有効にします。

      バージョン 3.3 で追加.

   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" を送出します。

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

         con.close()

   load_extension(path, /)

      *path* にある共有ライブラリから SQLite 拡張機能をロードします。
      このメソッドを呼び出す前に "enable_load_extension()" で拡張機能
      の読み込みを有効にしてください。

      引数 "connection", "path" を指定して 監査イベント
      "sqlite3.load_extension" を送出します。

      バージョン 3.2 で追加.

      バージョン 3.10 で変更: "sqlite3.load_extension" 監査イベントを
      追加しました。

   iterdump()

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

      例:

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

   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)

      バージョン 3.7 で追加.

   in_transaction

      この読み取り専用属性は、低レベルの SQLite autocommit mode に対応
      します。

      トランザクションがアクティブな場合 (コミットされていない変更があ
      る場合) は "True" 、それ以外の場合は "False" です。

      バージョン 3.2 で追加.

   isolation_level

      この属性は、 "sqlite3" によって実行される トランザクション処理
      を制御します。 "None" に設定すると、トランザクションが暗黙に開か
      れることはありません。背後の SQLite ライブラリのトランザクション
      の振る舞い(SQLite transaction behaviour)に対応する ""DEFERRED""
      または ""IMMEDIATE"" または ""EXCLUSIVE"" のいずれかに設定すると
      、暗黙の トランザクション制御 が実行されます。

      "connect()" の *isolation_level* パラメーターでオーバーライドさ
      れない場合、 デフォルトは """" で、 これは ""DEFERRED"" の別名で
      す。

   row_factory

      この接続から作成された "Cursor" オブジェクトの初期 "row_factory"
      。この属性に割り当てを行っても、 この接続に属する、すでに存在す
      るカーソルの "row_factory" には影響せず、 この属性に割り当てを行
      った後に作成する新しいカーソルのみに影響します。 デフォルトでは
      "None" です。つまり、各行は "タプル" として返されます。

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

   text_factory

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

      例:

         con = sqlite3.connect(":memory:")
         cur = con.cursor()

         AUSTRIA = "Österreich"

         # by default, rows are returned as str
         cur.execute("SELECT ?", (AUSTRIA,))
         row = cur.fetchone()
         assert row[0] == AUSTRIA

         # but we can make sqlite3 always return bytestrings ...
         con.text_factory = bytes
         cur.execute("SELECT ?", (AUSTRIA,))
         row = cur.fetchone()
         assert type(row[0]) is bytes
         # the bytestrings will be encoded in UTF-8, unless you stored garbage in the
         # database ...
         assert row[0] == AUSTRIA.encode("utf-8")

         # we can also implement a custom text_factory ...
         # here we implement one that appends "foo" to all strings
         con.text_factory = lambda x: x.decode("utf-8") + "foo"
         cur.execute("SELECT ?", ("bar",))
         row = cur.fetchone()
         assert row[0] == "barfoo"

         con.close()

   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 SQL a single SQL statement, optionally binding Python
      values using placeholders.

      パラメータ:
         * **sql** (*str*) -- A single SQL statement.

         * **parameters** ("dict" | *sequence*) -- Python values to
           bind to placeholders in *sql*. A "dict" if named
           placeholders are used. A *sequence* if unnamed placeholders
           are used. See プレースホルダを使用して SQL クエリに値を結び
           付ける方法.

      例外:
         **Warning** -- If *sql* contains more than one SQL statement.

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

      Use "executescript()" to execute multiple SQL statements.

   executemany(sql, parameters, /)

      For every item in *parameters*, repeatedly execute the
      parameterized SQL statement *sql*.

      Uses the same implicit transaction handling as "execute()".

      パラメータ:
         * **sql** (*str*) -- A single SQL DML (Data Manipulation
           Language) statement.

         * **parameters** (*iterable*) -- An *iterable* of parameters
           to bind with the placeholders in *sql*. See プレースホルダ
           を使用して SQL クエリに値を結び付ける方法.

      例外:
         * **ProgrammingError** -- If *sql* is not a DML statment.

         * **Warning** -- If *sql* contains more than one SQL
           statement.

      例:

         rows = [
             ("row1",),
             ("row2",),
         ]
         # cur is an sqlite3.Cursor object
         cur.executemany("INSERT INTO data VALUES(?)", rows)

   executescript(sql_script, /)

      *sql_script* 内の複数の SQL 文を実行します。 保留中のトランザク
      ションがある場合、 暗黙の "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

   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()" メソッドに
      よってのみ更新されます。

   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 で変更: スライスがサポートされました。


PrepareProtocol オブジェクト
----------------------------

class sqlite3.PrepareProtocol

   PrepareProtocol 型の唯一の目的は、 SQLite でネイティブにサポートさ
   れている型 に オブジェクト自身で適合(adapt) できるオブジェクトの
   **PEP 246** スタイルの適合プロトコルとして機能することです。


例外
----

例外の階層は DB-API 2.0 (**PEP 249**) で定義されています。

exception sqlite3.Warning

   This exception is raised by "sqlite3" if an SQL query is not a
   "string", or if multiple statements are passed to "execute()" or
   "executemany()". "Warning" is a subclass of "Exception".

exception sqlite3.Error

   このモジュールの他の例外の基底となるクラス。 これを使用すると、1 つ
   の "except" 文ですべてのエラーをキャッチできます。 "Error" は
   "Exception" のサブクラスです。

exception sqlite3.InterfaceError

   This exception is raised by "sqlite3" for fetch across rollback, or
   if "sqlite3" is unable to bind parameters. "InterfaceError" is a
   subclass of "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

   Exception raised for "sqlite3" API programming errors, for example
   trying to operate on a closed "Connection", or trying to execute
   non-DML statements with "executemany()". "ProgrammingError" is a
   subclass of "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 型に変換できます。


デフォルトの適合関数と変換関数
------------------------------

datetime モジュールの date 型および datetime 型のためのデフォルト適合
関数があります。これらの型は ISO 日付 / ISO タイムスタンプとして
SQLite に送られます。

デフォルトの変換関数は "datetime.date" 用が "date" という名前で、
"datetime.datetime" 用が "timestamp" という名前で登録されています。

これにより、多くの場合特別な細工無しに Python の日付 / タイムスタンプ
を使えます。適合関数の書式は実験的な SQLite の date/time 関数とも互換
性があります。

以下の例でこのことを確かめます。

   import sqlite3
   import datetime

   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
   cur = con.cursor()
   cur.execute("create table test(d date, ts timestamp)")

   today = datetime.date.today()
   now = datetime.datetime.now()

   cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
   cur.execute("select d, ts from test")
   row = cur.fetchone()
   print(today, "=>", row[0], type(row[0]))
   print(now, "=>", row[1], type(row[1]))

   cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
   row = cur.fetchone()
   print("current_date", row[0], type(row[0]))
   print("current_timestamp", row[1], type(row[1]))

   con.close()

SQLite に格納されているタイムスタンプが6桁より長い小数部を持っている場
合、タイムスタンプの変換関数によってマイクロ秒精度に丸められます。

注釈:

  デフォルトの "timestamp" 変換関数は、データベース内の UTC オフセット
  を無視し、常に素朴(naive)な "datetime.datetime" オブジェクトを返しま
  す。 timestamp で UTC オフセットを保持するには、変換関数を無効のまま
  にするか、あるいは、オフセット対応の変換関数を
  "register_converter()" に登録します。


ハウツー・ガイド
================


プレースホルダを使用して 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)

Instead, use the DB-API's parameter substitution. To insert a variable
into a query string, use a placeholder in the string, and substitute
the actual values into the query by providing them as a "tuple" of
values to the second argument of the cursor's "execute()" method.

An SQL statement may use one of two kinds of placeholders: question
marks (qmark style) or named placeholders (named style). For the qmark
style, *parameters* must be a *sequence* whose length must match the
number of placeholders, or a "ProgrammingError" is raised. For the
named style, *parameters* should be an instance of a "dict" (or a
subclass), which must contain keys for all named parameters; any extra
items are ignored. Here's an example of both styles:

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

注釈:

  **PEP 249** numeric placeholders are *not* supported. If used, they
  will be interpreted as named placeholders.


カスタム 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])


適合用呼び出し可能オブジェクト(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])


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


適合関数と変換関数のレシピ集
----------------------------

この節では一般的な適合関数と変換関数のレシピを紹介します。

   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" 文のブロックを離れるときに開いているトランザクションがない場合
、コンテキストマネージャは何もしません。

注釈:

  コンテキストマネージャは、新しいトランザクションを暗黙的に開いたり、
  接続を閉じたりしません。

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

パラメータのリストを含む、この機能の詳細については、 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

各列名が各値にマップされた "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}

以下の行工場(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

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


説明
====


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

"sqlite3" モジュールは、 **PEP 249** で推奨されているトランザクション
処理に準拠していません。

接続属性 "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文の前に、開いているトランザ
クションを暗黙にコミットしていました。これはもはや当てはまりません。
