diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6625511c783c39..a0b5c73d7a4ad4 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -25,6 +25,15 @@ The sqlite3 module was written by Gerhard Häring. It provides an SQL interface compliant with the DB-API 2.0 specification described by :pep:`249`, and requires SQLite 3.7.15 or newer. +This document includes four main sections: + +* :ref:`sqlite3-tutorial` teaches how to use the sqlite3 module. +* :ref:`sqlite3-reference` describes the classes and functions this module + defines. +* :ref:`sqlite3-howtos` details how to handle specific tasks. +* :ref:`sqlite3-explanation` provides in-depth background on + transaction control. + .. _sqlite3-tutorial: @@ -136,10 +145,15 @@ both styles: PEP written by Marc-André Lemburg. +.. _sqlite3-reference: + +Reference +--------- + .. _sqlite3-module-contents: Module functions and constants ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. data:: apilevel @@ -421,8 +435,8 @@ Module functions and constants .. _sqlite3-connection-objects: -Connection Objects ------------------- +Connection objects +^^^^^^^^^^^^^^^^^^ .. class:: Connection @@ -982,8 +996,8 @@ Connection Objects .. _sqlite3-cursor-objects: -Cursor Objects --------------- +Cursor objects +^^^^^^^^^^^^^^ A ``Cursor`` object represents a `database cursor`_ which is used to execute SQL statements, @@ -1159,8 +1173,8 @@ Cursor Objects .. _sqlite3-row-objects: -Row Objects ------------ +Row objects +^^^^^^^^^^^ .. class:: Row @@ -1224,8 +1238,8 @@ Now we plug :class:`Row` in:: .. _sqlite3-blob-objects: -Blob Objects ------------- +Blob objects +^^^^^^^^^^^^ .. versionadded:: 3.11 @@ -1276,8 +1290,8 @@ Blob Objects end). -PrepareProtocol Objects ------------------------ +PrepareProtocol objects +^^^^^^^^^^^^^^^^^^^^^^^ .. class:: PrepareProtocol @@ -1289,7 +1303,7 @@ PrepareProtocol Objects .. _sqlite3-exceptions: Exceptions ----------- +^^^^^^^^^^ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). @@ -1379,11 +1393,7 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). .. _sqlite3-types: SQLite and Python types ------------------------ - - -Introduction -^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^ SQLite natively supports the following types: ``NULL``, ``INTEGER``, ``REAL``, ``TEXT``, ``BLOB``. @@ -1423,10 +1433,18 @@ This is how SQLite types are converted to Python types by default: +-------------+----------------------------------------------+ The type system of the :mod:`sqlite3` module is extensible in two ways: you can -store additional Python types in an SQLite database via object adaptation, and -you can let the :mod:`sqlite3` module convert SQLite types to different Python -types via converters. +store additional Python types in an SQLite database via +:ref:`object adapters `, +and you can let the ``sqlite3`` module convert SQLite types to +Python types via :ref:`converters `. + + +.. _sqlite3-howtos: +How-to guides +------------- + +.. _sqlite3-adapters: Using adapters to store custom Python types in SQLite databases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1549,7 +1567,7 @@ The deprecated default adapters and converters consist of: .. _sqlite3-adapter-converter-recipes: -Adapter and Converter Recipes +Adapter and converter recipes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This section shows recipes for common adapters and converters. @@ -1592,83 +1610,6 @@ This section shows recipes for common adapters and converters. sqlite3.register_converter("timestamp", convert_timestamp) -.. _sqlite3-controlling-transactions: - -Controlling Transactions ------------------------- - -The ``sqlite3`` module does not adhere to the transaction handling recommended -by :pep:`249`. - -If the connection attribute :attr:`~Connection.isolation_level` -is not :const:`None`, -new transactions are implicitly opened before -:meth:`~Cursor.execute` and :meth:`~Cursor.executemany` executes -``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statements. -Use the :meth:`~Connection.commit` and :meth:`~Connection.rollback` methods -to respectively commit and roll back pending transactions. -You can choose the underlying `SQLite transaction behaviour`_ — -that is, whether and what type of ``BEGIN`` statements ``sqlite3`` -implicitly executes – -via the :attr:`~Connection.isolation_level` attribute. - -If :attr:`~Connection.isolation_level` is set to :const:`None`, -no transactions are implicitly opened at all. -This leaves the underlying SQLite library in `autocommit mode`_, -but also allows the user to perform their own transaction handling -using explicit SQL statements. -The underlying SQLite library autocommit mode can be queried using the -:attr:`~Connection.in_transaction` attribute. - -The :meth:`~Cursor.executescript` method implicitly commits -any pending transaction before execution of the given SQL script, -regardless of the value of :attr:`~Connection.isolation_level`. - -.. versionchanged:: 3.6 - :mod:`sqlite3` used to implicitly commit an open transaction before DDL - statements. This is no longer the case. - -.. _autocommit mode: - https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions - -.. _SQLite transaction behaviour: - https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions - - -.. _sqlite3-uri-tricks: - -SQLite URI tricks ------------------ - -Some useful URI tricks include: - -* Open a database in read-only mode:: - - con = sqlite3.connect("file:template.db?mode=ro", uri=True) - -* Do not implicitly create a new database file if it does not already exist; - will raise :exc:`~sqlite3.OperationalError` if unable to create a new file:: - - con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True) - -* Create a shared named in-memory database:: - - con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True) - con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True) - con1.execute("create table t(t)") - con1.execute("insert into t values(28)") - con1.commit() - rows = con2.execute("select * from t").fetchall() - -More information about this feature, including a list of parameters, -can be found in the `SQLite URI documentation`_. - -.. _SQLite URI documentation: https://www.sqlite.org/uri.html - -Using :mod:`sqlite3` efficiently --------------------------------- - - .. _sqlite3-connection-shortcuts: Using connection shortcut methods @@ -1686,6 +1627,8 @@ directly using only a single call on the :class:`Connection` object. .. literalinclude:: ../includes/sqlite3/shortcut_methods.py +.. _sqlite3-columns-by-name: + Accessing columns by name instead of by index ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1721,3 +1664,82 @@ the context manager is a no-op. nor closes the connection. .. literalinclude:: ../includes/sqlite3/ctx_manager.py + + +.. _sqlite3-uri-tricks: + +Working with SQLite URIs +^^^^^^^^^^^^^^^^^^^^^^^^ + +Some useful URI tricks include: + +* Open a database in read-only mode:: + + con = sqlite3.connect("file:template.db?mode=ro", uri=True) + +* Do not implicitly create a new database file if it does not already exist; + will raise :exc:`~sqlite3.OperationalError` if unable to create a new file:: + + con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True) + +* Create a shared named in-memory database:: + + con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True) + con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True) + con1.execute("create table t(t)") + con1.execute("insert into t values(28)") + con1.commit() + rows = con2.execute("select * from t").fetchall() + +More information about this feature, including a list of parameters, +can be found in the `SQLite URI documentation`_. + +.. _SQLite URI documentation: https://www.sqlite.org/uri.html + + +.. _sqlite3-explanation: + +Explanation +----------- + +.. _sqlite3-controlling-transactions: + +Transaction control +^^^^^^^^^^^^^^^^^^^ + +The ``sqlite3`` module does not adhere to the transaction handling recommended +by :pep:`249`. + +If the connection attribute :attr:`~Connection.isolation_level` +is not :const:`None`, +new transactions are implicitly opened before +:meth:`~Cursor.execute` and :meth:`~Cursor.executemany` executes +``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statements. +Use the :meth:`~Connection.commit` and :meth:`~Connection.rollback` methods +to respectively commit and roll back pending transactions. +You can choose the underlying `SQLite transaction behaviour`_ — +that is, whether and what type of ``BEGIN`` statements ``sqlite3`` +implicitly executes – +via the :attr:`~Connection.isolation_level` attribute. + +If :attr:`~Connection.isolation_level` is set to :const:`None`, +no transactions are implicitly opened at all. +This leaves the underlying SQLite library in `autocommit mode`_, +but also allows the user to perform their own transaction handling +using explicit SQL statements. +The underlying SQLite library autocommit mode can be queried using the +:attr:`~Connection.in_transaction` attribute. + +The :meth:`~Cursor.executescript` method implicitly commits +any pending transaction before execution of the given SQL script, +regardless of the value of :attr:`~Connection.isolation_level`. + +.. versionchanged:: 3.6 + :mod:`sqlite3` used to implicitly commit an open transaction before DDL + statements. This is no longer the case. + +.. _autocommit mode: + https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions + +.. _SQLite transaction behaviour: + https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions