diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/advanced.rst | 13 | ||||
| -rw-r--r-- | doc/src/conf.py | 4 | ||||
| -rw-r--r-- | doc/src/connection.rst | 76 | ||||
| -rw-r--r-- | doc/src/faq.rst | 4 |
4 files changed, 86 insertions, 11 deletions
diff --git a/doc/src/advanced.rst b/doc/src/advanced.rst index 3d95cb2..ac16ca9 100644 --- a/doc/src/advanced.rst +++ b/doc/src/advanced.rst @@ -239,9 +239,8 @@ be sent from Python code simply executing a :sql:`NOTIFY` command in an `~cursor.execute()` call. Because of the way sessions interact with notifications (see |NOTIFY|_ -documentation), you should keep the connection in :ref:`autocommit -<autocommit>` mode if you wish to receive or send notifications in a timely -manner. +documentation), you should keep the connection in `~connection.autocommit` +mode if you wish to receive or send notifications in a timely manner. .. |LISTEN| replace:: :sql:`LISTEN` .. _LISTEN: http://www.postgresql.org/docs/9.0/static/sql-listen.html @@ -373,12 +372,14 @@ When an asynchronous query is being executed, `connection.isexecuting()` returns connection. There are several limitations in using asynchronous connections: the -connection is always in :ref:`autocommit <autocommit>` mode and it is not -possible to change it using `~connection.set_isolation_level()`. So a +connection is always in `~connection.autocommit` mode and it is not +possible to change it. So a transaction is not implicitly started at the first query and is not possible to use methods `~connection.commit()` and `~connection.rollback()`: you can manually control transactions using `~cursor.execute()` to send database -commands such as :sql:`BEGIN`, :sql:`COMMIT` and :sql:`ROLLBACK`. +commands such as :sql:`BEGIN`, :sql:`COMMIT` and :sql:`ROLLBACK`. Similarly +`set_transaction()` can't be used but it is still possible to invoke the +:sql:`SET` command with the proper :sql:`default_transaction_...` parameter. With asynchronous connections it is also not possible to use `~connection.set_client_encoding()`, `~cursor.executemany()`, :ref:`large diff --git a/doc/src/conf.py b/doc/src/conf.py index 56a0768..db64f86 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -111,10 +111,10 @@ rst_epilog = """ .. _DBAPI: http://www.python.org/dev/peps/pep-0249/ .. _transaction isolation level: - http://www.postgresql.org/docs/9.0/static/transaction-iso.html + http://www.postgresql.org/docs/9.1/static/transaction-iso.html .. _serializable isolation level: - http://www.postgresql.org/docs/9.0/static/transaction-iso.html#XACT-SERIALIZABLE + http://www.postgresql.org/docs/9.1/static/transaction-iso.html#XACT-SERIALIZABLE .. _mx.DateTime: http://www.egenix.com/products/python/mxBase/mxDateTime/ diff --git a/doc/src/connection.rst b/doc/src/connection.rst index 0103258..9564095 100644 --- a/doc/src/connection.rst +++ b/doc/src/connection.rst @@ -327,11 +327,85 @@ The ``connection`` class pair: Transaction; Autocommit pair: Transaction; Isolation level - .. _autocommit: + .. method:: set_transaction(isolation_level=None, readonly=None, deferrable=None, autocommit=None) + + Set one or more parameters for the next transactions or statements in + the current session. See |SET TRANSACTION|_ for further details. + + .. |SET TRANSACTION| replace:: :sql:`SET TRANSACTION` + .. _SET TRANSACTION: http://www.postgresql.org/docs/9.1/static/sql-set-transaction.html + + :param isolation_level: set the `isolation level`_ for the next + transactions/statements. The value should be one of the + :ref:`constants <isolation-level-constants>` defined in the + `~psycopg2.extensions` module. + :param readonly: if `!True`, set the connection to read only; + read/write if `!False`. + :param deferrable: if `!True`, set the connection to deferrable; + non deferrable if `!False`. Only available from PostgreSQL 9.1. + :param autocommit: switch the connection to autocommit mode: not a + PostgreSQL session setting but an alias for setting the + `autocommit` attribute. + + .. _isolation level: + http://www.postgresql.org/docs/9.1/static/transaction-iso.html + + The function must be invoked with no transaction in progress. At every + function invocation, only the parameters whose value is not `!None` are + changed. + + The default for the values are defined by the server configuration: + see values for |default_transaction_isolation|__, + |default_transaction_read_only|__, |default_transaction_deferrable|__. + + .. |default_transaction_isolation| replace:: :sql:`default_transaction_isolation` + .. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION + .. |default_transaction_read_only| replace:: :sql:`default_transaction_read_only` + .. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY + .. |default_transaction_deferrable| replace:: :sql:`default_transaction_deferrable` + .. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-DEFERRABLE + + .. note:: + + There is currently no builtin method to read the current value for + the parameters: use :sql:`SHOW default_transaction_...` to read + the values from the backend. + + .. versionadded:: 2.4.2 + + + .. attribute:: autocommit + + Read/write attribute: if `!True`, no transaction is handled by the + driver and every statement sent to the backend has immediate effect; + if `!False` a new transaction is started at the first command + execution: the methods `commit()` or `rollback()` must be manually + invoked to terminate the transaction. + + The default is `!False` (manual commit) as per DBAPI specification. + + .. warning:: + + By default, any query execution, including a simple :sql:`SELECT` + will start a transaction: for long-running program, 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. + + .. versionadded:: 2.4.2 + .. attribute:: isolation_level .. method:: set_isolation_level(level) + .. note:: + + From version 2.4.2, replaced by `set_transaction()` and + `autocommit`, offering finer control on the transaction + characteristics. + Read or set the `transaction isolation level`_ for the current session. The level defines the different phenomena that can happen in the database between concurrent transactions. diff --git a/doc/src/faq.rst b/doc/src/faq.rst index 4ebf15a..e7fe76f 100644 --- a/doc/src/faq.rst +++ b/doc/src/faq.rst @@ -22,8 +22,8 @@ Why does `!psycopg2` leave database sessions "idle in transaction"? call one of the transaction closing methods before leaving the connection unused for a long time (which may also be a few seconds, depending on the concurrency level in your database). Alternatively you can use a - connection in :ref:`autocommit <autocommit>` mode to avoid a new - transaction to be started at the first command. + connection in `~connection.autocommit` mode to avoid a new transaction to + be started at the first command. I receive the error *current transaction is aborted, commands ignored until end of transaction block* and can't do anything else! There was a problem *in the previous* command to the database, which |