From fc37948d6961db80aa131bd76651d8e25c700b72 Mon Sep 17 00:00:00 2001 From: Pierre-Louis Bonicoli Date: Mon, 12 Nov 2012 02:04:52 +0100 Subject: [PATCH] Use "connection"/"db session" instead of "session" --- doc/src/connection.rst | 35 +++++++++++++++++------------------ doc/src/module.rst | 2 +- doc/src/usage.rst | 29 ++++++++++++++--------------- 3 files changed, 32 insertions(+), 34 deletions(-) diff --git a/doc/src/connection.rst b/doc/src/connection.rst index cc34155..dd48596 100644 --- a/doc/src/connection.rst +++ b/doc/src/connection.rst @@ -12,8 +12,7 @@ The ``connection`` class .. class:: connection - Handles the connection to a PostgreSQL database instance. It encapsulates - a database session. + Handles the connection to a PostgreSQL database instance. Connections are created using the factory function `~psycopg2.connect()`. @@ -316,8 +315,8 @@ The ``connection`` class The method rolls back an eventual pending transaction and executes the PostgreSQL |RESET|_ and |SET SESSION AUTHORIZATION|__ to revert the - session to the default values. A two-phase commit transaction prepared - using `~connection.tpc_prepare()` will remain in the database + connection to the default values. A two-phase commit transaction + prepared using `~connection.tpc_prepare()` will remain in the database available for recover. .. |RESET| replace:: :sql:`RESET` @@ -342,7 +341,7 @@ The ``connection`` class .. method:: set_session([isolation_level,] [readonly,] [deferrable,] [autocommit]) Set one or more parameters for the next transactions or statements in - the current session. See |SET TRANSACTION|_ for further details. + the current connection. See |SET TRANSACTION|_ for further details. .. |SET TRANSACTION| replace:: :sql:`SET TRANSACTION` .. _SET TRANSACTION: http://www.postgresql.org/docs/current/static/sql-set-transaction.html @@ -409,11 +408,11 @@ The ``connection`` class By default, any query execution, including a simple :sql:`SELECT` 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 - ensure to terminate a transaction as soon as possible or use an - autocommit connection. + action is taken, the database connection will remain "idle in + transaction", a condition non desiderable for several reasons + (locks are held by the connection, 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 @@ -426,9 +425,9 @@ The ``connection`` class From version 2.4.2, `set_session()` and `autocommit`, offer 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. + Read or set the `transaction isolation level`_ for the current + connection. The level defines the different phenomena that can happen + in the database between concurrent transactions. The value set or read is an integer: symbolic constants are defined in the module `psycopg2.extensions`: see @@ -450,7 +449,7 @@ The ``connection`` class .. attribute:: encoding .. method:: set_client_encoding(enc) - Read or set the client encoding for the current session. The default + Read or set the client encoding for the current connection. The default is the encoding defined by the database. It should be one of the `characters set supported by PostgreSQL`__ @@ -463,7 +462,7 @@ The ``connection`` class .. attribute:: notices A list containing all the database messages sent to the client during - the session. + the connection. .. doctest:: :options: NORMALIZE_WHITESPACE @@ -486,7 +485,7 @@ The ``connection`` class .. attribute:: notifies List of `~psycopg2.extensions.Notify` objects containing asynchronous - notifications received by the session. + notifications received by the connection. For other details see :ref:`async-notify`. @@ -540,8 +539,8 @@ The ``connection`` class .. method:: get_transaction_status() - Return the current session transaction status as an integer. Symbolic - constants for the values are defined in the module + Return the current connection transaction status as an integer. + Symbolic constants for the values are defined in the module `psycopg2.extensions`: see :ref:`transaction-status-constants` for the available values. diff --git a/doc/src/module.rst b/doc/src/module.rst index 35292ba..07c13e7 100644 --- a/doc/src/module.rst +++ b/doc/src/module.rst @@ -18,7 +18,7 @@ The module interface respects the standard defined in the |DBAPI|_. .. function:: connect(dsn or params [, connection_factory] [, async=0]) - Create a new database session and return a new `connection` object. + Create a new database connection and return a new `connection` object. The connection parameters can be specified either as a string:: diff --git a/doc/src/usage.rst b/doc/src/usage.rst index 136f677..0215e70 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -41,15 +41,15 @@ basic commands:: The main entry points of Psycopg are: -- The function `~psycopg2.connect()` creates a new database session and +- The function `~psycopg2.connect()` creates a new database connection and returns a new `connection` instance. -- The class `connection` encapsulates a database session. It allows to: +- The class `connection` encapsulates a database connection. It allows to: - create new `cursor`\s using the `~connection.cursor()` method to execute database commands and queries, - - terminate the session using the methods `~connection.commit()` or + - terminate the transaction using the methods `~connection.commit()` or `~connection.rollback()`. - The class `cursor` allows interaction with the database: @@ -527,20 +527,20 @@ 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: you can use the +Psycopg, the connection must be in autocommit mode: you can use the `~connection.autocommit` property (`~connection.set_isolation_level()` in older versions). .. warning:: By default even a simple :sql:`SELECT` will start a transaction: in - long-running programs, if no further action is taken, the session will + long-running programs, if no further action is taken, the connection 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 make sure 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 +A few other transaction properties can be set connection-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. @@ -646,17 +646,16 @@ Thread and process safety ------------------------- The Psycopg module and the `connection` objects are *thread-safe*: many -threads can access the same database either using separate sessions and -creating a `!connection` per thread or using the same -connection and creating separate `cursor`\ s. In |DBAPI|_ parlance, Psycopg is -*level 2 thread safe*. +threads can access the same database either using separate connection (creating +a `!connection` per thread) or using the same connection and creating separate +`cursor`\ s. In |DBAPI|_ parlance, Psycopg is *level 2 thread safe*. The difference between the above two approaches is that, using different -connections, the commands will be executed in different sessions and will be -served by different server processes. On the other hand, using many cursors on -the same connection, all the commands will be executed in the same session -(and in the same transaction if the connection is not in :ref:`autocommit -` mode), but they will be serialized. +connections, the commands will be executed in different database sessions and +will be served by different server processes. On the other hand, using many +cursors on the same connection, all the commands will be executed in the same +database session (and in the same transaction if the connection is not in +:ref:`autocommit ` mode), but they will be serialized. The above observations are only valid for regular threads: they don't apply to forked processes nor to green threads. `libpq` connections `shouldn't be used by a -- 1.7.10.4