diff -r a32ced15b883 Doc/library/sqlite3.rst --- a/Doc/library/sqlite3.rst Fri Jun 06 01:27:34 2014 -0500 +++ b/Doc/library/sqlite3.rst Fri Jun 06 16:09:30 2014 +0200 @@ -166,7 +166,7 @@ first blank for the column name: the column name would simply be "x". -.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri]) +.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri, transaction_mode]) Opens a connection to the SQLite database file *database*. You can use ``":memory:"`` to open a database connection to a database that resides in RAM @@ -180,6 +180,15 @@ For the *isolation_level* parameter, please see the :attr:`Connection.isolation_level` property of :class:`Connection` objects. + This parameter is deprecated. Use *transaction_mode* instead. + + By default, SQLite 3 operates in autocommit mode. To comply with PEP 249, + the :mod:`sqlite3` module emulates non-autocommit mode. The + *transaction_mode* parameter provides finer control of this behavior. It + may be set to ``'legacy'`` (default), ``'legacy deferred'``", ``'legacy + immediate'``", ``'legacy exclusive'``", ``''``, ``'deferred'``", + ``'immediate'``", ``'exclusive'``" or ``'autocommit'``. See section + :ref:`sqlite3-controlling-transactions` for a more detailed explanation. SQLite natively supports only the types TEXT, INTEGER, REAL, BLOB and NULL. If you want to use other types you must add support for them yourself. The @@ -214,6 +223,8 @@ .. versionchanged:: 3.4 Added the *uri* parameter. + .. versionchanged:: 3.5 + Added the *transaction_mode* parameter. .. function:: register_converter(typename, callable) @@ -263,17 +274,52 @@ A SQLite database connection has the following attributes and methods: + .. attribute:: transaction_mode + + Get or set the transaction mode, one of ``'legacy'`` (default), + ``'legacy deferred'``", ``'legacy immediate'``", ``'legacy + exclusive'``", ``'standard'``, ``'standard deferred'``", ``'standard + immediate'``", ``'standard exclusive'``" or ``'autocommit'``. This + attribute cannot be changed while a transaction is active. Commit or + rollback the transaction first. See section + :ref:`sqlite3-controlling-transactions` for a more detailed explanation. + + .. versionadded:: 3.5 + + .. attribute:: autocommit + + Short-hand property to get or set :attr:`transaction_mode` to common + values. :const:`True` if :attr:`transaction_mode` is ``'autocommit'``, + :const:`False` otherwise. Setting it to :const:`True` sets + :attr:`transaction_mode` to ``'autocommit'``, setting it to + :const:`False` sets :attr:`transaction_mode` to ``'standard'``. (This + differs from the default value for :attr:`transaction_mode` which is + ``'legacy'`` for backwards-compatibility reasons.) + + .. versionadded:: 3.5 + .. attribute:: isolation_level - Get or set the current 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. + 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. + + .. warning:: + This parameter is unrelated with the concept of isolation levels. + SQLite runs at the SERIALIZABLE isolation level (unless you've + enabled cache sharing and ``PRAGMA read_uncommitted;``). + + This attribute is deprecated. Use *transaction_mode* instead. .. attribute:: in_transaction :const:`True` if a transaction is active (there are uncommitted changes), :const:`False` otherwise. Read-only attribute. + This is an implementation detail of the legacy mode. For the purpose of + transaction management, you should use *autocommit* instead. + .. versionadded:: 3.2 .. method:: cursor([cursorClass]) @@ -857,7 +903,24 @@ Controlling Transactions ------------------------ -By default, the :mod:`sqlite3` module opens transactions implicitly before a +The underlying SQLite 3 library operates in ``autocommit`` mode by default, +but the Python :mod:`sqlite3`` module by default does not, in order to comply +with PEP 249. + +The :mod:`sqlite3`` module offers three main transaction management modes, +controlled by *transaction_mode*: ``'legacy'`` (default), ``'standard'`` and +``'autocommit'``. + +In addition, the legacy and standard mode can use a particular transaction +behavior: none (default), ``'deferred'``, ``'immediate'`` or ``'exclusive'``. + +.. versionchanged:: 3.5 + Added *transaction_mode* and introduced the standard mode. + +Legacy mode +^^^^^^^^^^^ + +In this mode, 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. @@ -871,16 +934,61 @@ is active or not). The current transaction state is exposed through the :attr:`Connection.in_transaction` attribute of the connection object. +The :mod:`sqlite3` module also commits implicitly before ``SAVEPOINT`` +statements, making it impossible to use savepoints in legacy mode. + You can control which kind of ``BEGIN`` statements sqlite3 implicitly executes -(or none at all) via the *isolation_level* parameter to the :func:`connect` -call, or via the :attr:`isolation_level` property of connections. +by specifying a transaction behavior (see below). -If you want **autocommit mode**, then set :attr:`isolation_level` to None. +For backwards compatibility reasons, this is the default. If you care about +compliance with PEP 249, you may be better served by the standard mode. If you +care about performance, you should probably use the autocommit mode. -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". +Standard mode +^^^^^^^^^^^^^ +In this mode, the :mod:`sqlite3` module opens a transaction implicitly before +any statement, unless a transaction is already active. This adheres more +closely to PEP 249 semantics, possibly at the cost of performance under +concurrent workloads. + +It never commits transactions implicitly. There are two reasons for doing +that. The first is that many non-DML, non-query statements such as +``SAVEPOINT`` make perfect sense inside a transaction. The second is that +implicit commits can subtly invalidate transactional integrity. + +Autocommit mode +^^^^^^^^^^^^^^^ + +``'autocommit'`` mode means that statements that modify the database take +effect immediately, without needing to call ``commit()``. + +This mode provides the default semantics of the SQLite 3 library, without any +interference of the :mod:`sqlite3` module. You can implement your own +transaction managament features as needed. + +The proper way to start a transaction is to switch to the ``'standard'`` mode. +Then, before the next statement runs, a ``BEGIN`` statement will be issued +automatically, starting a transaction. This also happens after each +``commit()`` or ``rollback()``. + +To return to autocommit, first run ``commit()`` or a ``rollback()`` to end the +current transaction, then switch back to the ``'autocommit'`` mode. + +.. warning:: + Don't execute explicit ``BEGIN``, ``COMMIT`` or ``ROLLBACK`` statements! + The :mod:`sqlite3` module needs to keep track of the transaction state. + Such statements could leave it out of sync. + +Transaction behaviors +^^^^^^^^^^^^^^^^^^^^^ + +Transaction behavior controls whether :mod:`sqlite3` emits a ``BEGIN``, +``BEGIN DEFERRED``, ``BEGIN IMMEDIATE`` or ``BEGIN EXCLUSIVE`` when it opens a +transaction implicitly in legacy or standard mode. See SQLite's documentation +of `BEGIN TRANSACTION`_ for details. + +.. _BEGIN TRANSACTION: http://www.sqlite.org/lang_transaction.html Using :mod:`sqlite3` efficiently @@ -916,13 +1024,23 @@ Using the connection as a context manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Connection objects can be used as context managers -that automatically commit or rollback transactions. In the event of an -exception, the transaction is rolled back; otherwise, the transaction is -committed: +Connection objects can be used as context managers that automatically commit +or rollback transactions. In the event of an exception, the transaction is +rolled back; otherwise, the transaction is committed: .. literalinclude:: ../includes/sqlite3/ctx_manager.py +Such context managers don't have any effect in autocommit mode. They're +designed for the legacy and default modes. + +.. warning:: + + Don't nest these context managers! + + If you do, when you exit successfully the inner context, all changes up to + this point are committed to the database. If an exception is raised later + in the outer context, the rollback will only go back to the end of the + inner block, not to the beginning of the outer block like you would expect. Common issues -------------