diff --git a/NEWS b/NEWS index d2f8a458..679486bc 100644 --- a/NEWS +++ b/NEWS @@ -1,6 +1,10 @@ What's new in psycopg 2.4.6 --------------------------- + - Added support for backward scrollable cursors. Thanks to Jon Nelson + for the initial patch (ticket #108). + - connection.reset() implemented using DISCARD ALL on server versions + supporting it. - Fixed 'cursor()' arguments propagation in connection subclasses and overriding of the 'cursor_factory' argument. Thanks to Corry Haines for the report and the initial patch (ticket #105). @@ -9,8 +13,6 @@ What's new in psycopg 2.4.6 Thanks to Manu Cupcic for the report (ticket #110). - 'register_hstore()', 'register_composite()', 'tpc_recover()' work with RealDictConnection and Cursor (ticket #114). - - connection.reset() implemented using DISCARD ALL on server versions - supporting it. What's new in psycopg 2.4.5 diff --git a/doc/src/connection.rst b/doc/src/connection.rst index e0b34ab8..cc341553 100644 --- a/doc/src/connection.rst +++ b/doc/src/connection.rst @@ -21,16 +21,17 @@ The ``connection`` class Connections are thread safe and can be shared among many threads. See :ref:`thread-safety` for details. - .. method:: cursor([name] [, cursor_factory] [, withhold]) + .. method:: cursor(name=None, cursor_factory=None, scrollable=None, withhold=False) Return a new `cursor` object using the connection. If *name* is specified, the returned cursor will be a :ref:`server side cursor ` (also known as *named cursor*). - Otherwise it will be a regular *client side* cursor. By default a - :sql:`WITHOUT HOLD` cursor is created; to create a :sql:`WITH HOLD` - cursor, pass a `!True` value as the *withhold* parameter. See - :ref:`server-side-cursors`. + Otherwise it will be a regular *client side* cursor. By default a + named cursor is declared without :sql:`SCROLL` option and + :sql:`WITHOUT HOLD`: set the argument or property `~cursor.scrollable` + to `!True`/`!False` and or `~cursor.withhold` to `!True` to change the + declaration. The name can be a string not valid as a PostgreSQL identifier: for example it may start with a digit and contain non-alphanumeric @@ -46,14 +47,16 @@ The ``connection`` class Consider it as part of the query, not as a query parameter. The *cursor_factory* argument can be used to create non-standard - cursors. The class returned should be a subclass of + cursors. The class returned must be a subclass of `psycopg2.extensions.cursor`. See :ref:`subclassing-cursor` for details. + .. versionchanged:: 2.4.3 added the *withhold* argument. + .. versionchanged:: 2.4.6 added the *scrollable* argument. + .. extension:: - The `name` and `cursor_factory` parameters are Psycopg - extensions to the |DBAPI|. + All the function arguments are Psycopg extensions to the |DBAPI|. .. index:: diff --git a/doc/src/cursor.rst b/doc/src/cursor.rst index 4b8495ae..3a17ebe1 100644 --- a/doc/src/cursor.rst +++ b/doc/src/cursor.rst @@ -114,20 +114,51 @@ The ``cursor`` class The `name` attribute is a Psycopg extension to the |DBAPI|. + .. attribute:: scrollable + + Read/write attribute: specifies if a named cursor is declared + :sql:`SCROLL`, hence is capable to scroll backwards (using + `~cursor.scroll()`). If `!True`, the cursor can be scrolled backwards, + if `!False` it is never scrollable. If `!None` (default) the cursor + scroll option is not specified, usually but not always meaning no + backward scroll (see the |declare-notes|__). + + .. |declare-notes| replace:: :sql:`DECLARE` notes + .. __: http://www.postgresql.org/docs/current/static/sql-declare.html#SQL-DECLARE-NOTES + + .. note:: + + set the value before calling `~cursor.execute()` or use the + `connection.cursor()` *scrollable* parameter, otherwise the value + will have no effect. + + .. versionadded:: 2.4.6 + + .. extension:: + + The `scrollable` attribute is a Psycopg extension to the |DBAPI|. + + .. attribute:: withhold - + Read/write attribute: specifies if a named cursor lifetime should extend outside of the current transaction, i.e., it is possible to - fetch from the cursor even after a `commection.commit()` (but not after + fetch from the cursor even after a `connection.commit()` (but not after a `connection.rollback()`). See :ref:`server-side-cursors` + .. note:: + + set the value before calling `~cursor.execute()` or use the + `connection.cursor()` *withhold* parameter, otherwise the value + will have no effect. + .. versionadded:: 2.4.3 - + .. extension:: The `withhold` attribute is a Psycopg extension to the |DBAPI|. - - + + .. |execute*| replace:: `execute*()` .. _execute*: @@ -297,7 +328,8 @@ The ``cursor`` class not changed. The method can be used both for client-side cursors and - :ref:`server-side cursors `. + :ref:`server-side cursors `. Server-side cursors + can usually scroll backwards only if declared `~cursor.scrollable`. .. note:: diff --git a/doc/src/usage.rst b/doc/src/usage.rst index 6abaf51b..00df4c93 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -576,7 +576,9 @@ cursor is created using the `~connection.cursor()` method specifying the *name* parameter. Such cursor will behave mostly like a regular cursor, allowing the user to move in the dataset using the `~cursor.scroll()` method and to read the data using `~cursor.fetchone()` and -`~cursor.fetchmany()` methods. +`~cursor.fetchmany()` methods. Normally you can only scroll forward in a +cursor: if you need to scroll backwards you should declare your cursor +`~cursor.scrollable`. Named cursors are also :ref:`iterable ` like regular cursors. Note however that before Psycopg 2.4 iteration was performed fetching one