diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -246,7 +246,7 @@ .. attribute:: isolation_level - Get or set the current isolation level. :const:`None` for autocommit mode or + Get or set the current default isolation level. :const:`None` for autocommit mode or one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section :ref:`sqlite3-controlling-transactions` for a more detailed explanation. @@ -820,13 +820,23 @@ Controlling Transactions ------------------------ -By default, the :mod:`sqlite3` module opens transactions implicitly before a -Data Modification Language (DML) statement (i.e. -``INSERT``/``UPDATE``/``DELETE``/``REPLACE``), and commits transactions -implicitly before a non-DML, non-query statement (i. e. -anything other than ``SELECT`` or the aforementioned). +The underlying ``sqlite3`` library operates in ``autocommit`` mode by +default, but the Python ``sqlite3`` module by default does not. -So if you are within a transaction and issue a command like ``CREATE TABLE +``autocommit`` mode means that statements that modify the database take effect +immediately. A ``BEGIN`` or ``SAVEPOINT`` statement disables autocommit mode, +and a ``COMMIT`` or a ``ROLLBACK``, or a ``RELEASE`` that ends the outermost +transaction, turns ``autocommit`` mode back on. + +The Python ``sqlite3`` module by default issues a ``BEGIN`` statement +implicitly before a Data Modification Language (DML) statement (i.e. +``INSERT``/``UPDATE``/``DELETE``/``REPLACE``), and issues a ``COMMIT`` +statement implicitly before a non-DML, non-query statement (that is, anything +other than ``SELECT`` or the aforementioned). + +So if you are within a transaction (whether started explicitly by your code +or implicitly by issuing one of the DML statements above) and issue a command +like ``CREATE TABLE ...``, ``VACUUM``, ``PRAGMA``, the :mod:`sqlite3` module will commit implicitly before executing that command. There are two reasons for doing that. The first is that some of these commands don't work within transactions. The other reason @@ -834,15 +844,18 @@ is active or not). The current transaction state is exposed through the :attr:`Connection.in_transaction` attribute of the connection object. -You can control which kind of ``BEGIN`` statements sqlite3 implicitly executes -(or none at all) via the *isolation_level* parameter to the :func:`connect` +You can control which kind of ``BEGIN`` statements :mod:`sqlite3` implicitly +executes via the *isolation_level* parameter to the :func:`connect` call, or via the :attr:`isolation_level` property of connections. +If you specify no *isolation_level*, a plain ``BEGIN`` is used, which is +equivalent to specifying ``DEFERRED``. Other possible values are ``IMMEDIATE`` +and ``EXCLUSIVE``. -If you want **autocommit mode**, then set :attr:`isolation_level` to None. - -Otherwise leave it at its default, which will result in a plain "BEGIN" -statement, or set it to one of SQLite's supported isolation levels: "DEFERRED", -"IMMEDIATE" or "EXCLUSIVE". +You can disable the ``sqlite3`` module's implicit transaction management by +setting :attr:`isolation_level` to ``None``. This will leave the underlying +``sqlite3`` library operating in ``autocommit`` mode. You can then completely +control the transaction state by explicitly issuing ``BEGIN``, ``ROLLBACK``, +``SAVEPOINT``, and ``RELEASE`` statements in your code.