From d76d136b4f3bb2a88a64ad83e8f26fb2b486a604 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Wed, 8 Jun 2011 14:38:57 +0100 Subject: [PATCH] Introductory docs section on transaction control improved Added big fat warning about idle in transaction and reference to set_session(). --- doc/src/connection.rst | 2 +- doc/src/usage.rst | 24 +++++++++++++++++------- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/doc/src/connection.rst b/doc/src/connection.rst index a38a560a..2763e066 100644 --- a/doc/src/connection.rst +++ b/doc/src/connection.rst @@ -396,7 +396,7 @@ The ``connection`` class .. warning:: By default, any query execution, including a simple :sql:`SELECT` - will start a transaction: for long-running program, if no further + will start a transaction: for long-running programs, if no further action is taken, the session will remain "idle in transaction", a condition non desiderable for several reasons (locks are held by the session, tables bloat...). For long lived scripts, either diff --git a/doc/src/usage.rst b/doc/src/usage.rst index efbd1587..5f6c5b1c 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -489,7 +489,7 @@ rounded to the nearest minute, with an error of up to 30 seconds. versions use `psycopg2.extras.register_tstz_w_secs()`. -.. index:: Transaction, Begin, Commit, Rollback, Autocommit +.. index:: Transaction, Begin, Commit, Rollback, Autocommit, Read only .. _transactions-control: @@ -503,7 +503,7 @@ The following database commands will be executed in the context of the same transaction -- not only the commands issued by the first cursor, but the ones issued by all the cursors created by the same connection. Should any command fail, the transaction will be aborted and no further command will be executed -until a call to the `connection.rollback()` method. +until a call to the `~connection.rollback()` method. The connection is responsible to terminate its transaction, calling either the `~connection.commit()` or `~connection.rollback()` method. Committed @@ -516,13 +516,23 @@ It is possible to set the connection in *autocommit* mode: this way all the commands executed will be immediately committed and no rollback is possible. A few commands (e.g. :sql:`CREATE DATABASE`, :sql:`VACUUM`...) require to be run outside any transaction: in order to be able to run these commands from -Psycopg, the session must be in autocommit mode. Read the documentation for -`connection.set_isolation_level()` to know how to change the commit mode. +Psycopg, the session must be in autocommit mode: you can use the +`~connection.autocommit` property (`~connection.set_isolation_level()` in +older versions). -.. note:: +.. warning:: - From version 2.4.2 you can use the `~connection.autocommit` property to - switch a connection in autocommit mode. + By default even a simple :sql:`SELECT` will start a transaction: in + long-running programs, if no further action is taken, the session will + remain "idle in transaction", a condition non desiderable for several + reasons (locks are held by the session, tables bloat...). For long lived + scripts, either ensure to terminate a transaction as soon as possible or + use an autocommit connection. + +A few other transaction properties can be set session-wide by the +`!connection`: for instance it is possible to have read-only transactions or +change the isolation level. See the `~connection.set_session()` method for all +the details. .. index::