Skip to content

Commit a71fed0

Browse files
berkerpeksagzooba
authored andcommitted
bpo-8145: Improve isolation_level documentation (GH-8499)
Initial patch by R. David Murray.
1 parent 11eb1a9 commit a71fed0

File tree

1 file changed

+22
-14
lines changed

1 file changed

+22
-14
lines changed

Doc/library/sqlite3.rst

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -281,7 +281,7 @@ Connection Objects
281281

282282
.. attribute:: isolation_level
283283

284-
Get or set the current isolation level. :const:`None` for autocommit mode or
284+
Get or set the current default isolation level. :const:`None` for autocommit mode or
285285
one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section
286286
:ref:`sqlite3-controlling-transactions` for a more detailed explanation.
287287

@@ -1010,22 +1010,30 @@ timestamp converter.
10101010
Controlling Transactions
10111011
------------------------
10121012

1013-
By default, the :mod:`sqlite3` module opens transactions implicitly before a
1014-
Data Modification Language (DML) statement (i.e.
1015-
``INSERT``/``UPDATE``/``DELETE``/``REPLACE``).
1016-
1017-
You can control which kind of ``BEGIN`` statements sqlite3 implicitly executes
1018-
(or none at all) via the *isolation_level* parameter to the :func:`connect`
1019-
call, or via the :attr:`isolation_level` property of connections.
1013+
The underlying ``sqlite3`` library operates in ``autocommit`` mode by default,
1014+
but the Python :mod:`sqlite3` module by default does not.
10201015

1021-
If you want **autocommit mode**, then set :attr:`isolation_level` to ``None``.
1016+
``autocommit`` mode means that statements that modify the database take effect
1017+
immediately. A ``BEGIN`` or ``SAVEPOINT`` statement disables ``autocommit``
1018+
mode, and a ``COMMIT``, a ``ROLLBACK``, or a ``RELEASE`` that ends the
1019+
outermost transaction, turns ``autocommit`` mode back on.
10221020

1023-
Otherwise leave it at its default, which will result in a plain "BEGIN"
1024-
statement, or set it to one of SQLite's supported isolation levels: "DEFERRED",
1025-
"IMMEDIATE" or "EXCLUSIVE".
1021+
The Python :mod:`sqlite3` module by default issues a ``BEGIN`` statement
1022+
implicitly before a Data Modification Language (DML) statement (i.e.
1023+
``INSERT``/``UPDATE``/``DELETE``/``REPLACE``).
10261024

1027-
The current transaction state is exposed through the
1028-
:attr:`Connection.in_transaction` attribute of the connection object.
1025+
You can control which kind of ``BEGIN`` statements :mod:`sqlite3` implicitly
1026+
executes via the *isolation_level* parameter to the :func:`connect`
1027+
call, or via the :attr:`isolation_level` property of connections.
1028+
If you specify no *isolation_level*, a plain ``BEGIN`` is used, which is
1029+
equivalent to specifying ``DEFERRED``. Other possible values are ``IMMEDIATE``
1030+
and ``EXCLUSIVE``.
1031+
1032+
You can disable the :mod:`sqlite3` module's implicit transaction management by
1033+
setting :attr:`isolation_level` to ``None``. This will leave the underlying
1034+
``sqlite3`` library operating in ``autocommit`` mode. You can then completely
1035+
control the transaction state by explicitly issuing ``BEGIN``, ``ROLLBACK``,
1036+
``SAVEPOINT``, and ``RELEASE`` statements in your code.
10291037

10301038
.. versionchanged:: 3.6
10311039
:mod:`sqlite3` used to implicitly commit an open transaction before DDL

0 commit comments

Comments
 (0)