diff --git a/Doc/includes/sqlite3/ctx_manager.py b/Doc/includes/sqlite3/ctx_manager.py new file mode 100644 index 00000000000..27dd0b5834f --- /dev/null +++ b/Doc/includes/sqlite3/ctx_manager.py @@ -0,0 +1,16 @@ +import sqlite3 + +con = sqlite3.connect(":memory:") +con.execute("create table person (id integer primary key, firstname varchar unique)") + +# Successful, con.commit() is called automatically afterwards +with con: + con.execute("insert into person(firstname) values (?)", ("Joe",)) + +# con.rollback() is called after the with block finishes with an exception, the +# exception is still raised and must be catched +try: + with con: + con.execute("insert into person(firstname) values (?)", ("Joe",)) +except sqlite3.IntegrityError: + print "couldn't add Joe twice" diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index da313fd5976..29d5e490b74 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -232,6 +232,24 @@ A :class:`Connection` instance has the following attributes and methods: :class:`sqlite3.Cursor`. +.. method:: Connection.commit() + + This method commits the current transaction. If you don't call this method, + anything you did since the last call to commit() is not visible from from + other database connections. If you wonder why you don't see the data you've + written to the database, please check you didn't forget to call this method. + +.. method:: Connection.rollback() + + This method rolls back any changes to the database since the last call to + :meth:`commit`. + +.. method:: Connection.close() + + This closes the database connection. Note that this does not automatically + call :meth:`commit`. If you just close your database connection without + calling :meth:`commit` first, your changes will be lost! + .. method:: Connection.execute(sql, [parameters]) This is a nonstandard shortcut that creates an intermediate cursor object by @@ -245,7 +263,6 @@ A :class:`Connection` instance has the following attributes and methods: calling the cursor method, then calls the cursor's :meth:`executemany` method with the parameters given. - .. method:: Connection.executescript(sql_script) This is a nonstandard shortcut that creates an intermediate cursor object by @@ -332,6 +349,19 @@ A :class:`Connection` instance has the following attributes and methods: one. All necessary constants are available in the :mod:`sqlite3` module. +.. method:: Connection.set_progress_handler(handler, n) + + .. versionadded:: 2.6 + + This routine registers a callback. The callback is invoked for every *n* + instructions of the SQLite virtual machine. This is useful if you want to + get called from SQLite during long-running operations, for example to update + a GUI. + + If you want to clear any previously installed progress handler, call the + method with :const:`None` for *handler*. + + .. attribute:: Connection.row_factory You can change this attribute to a callable that accepts the cursor and the @@ -701,10 +731,6 @@ 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. -As the :mod:`sqlite3` module needs to keep track of the transaction state, you -should not use ``OR ROLLBACK`` or ``ON CONFLICT ROLLBACK`` in your SQL. Instead, -catch the :exc:`IntegrityError` and call the :meth:`rollback` method of the -connection yourself. Using pysqlite efficiently @@ -736,3 +762,15 @@ case-insensitively by name: .. literalinclude:: ../includes/sqlite3/rowclass.py + +Using the connection as a context manager +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 2.6 + +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