.. _async:
-Async operations
-================
+Asynchronous operations
+=======================
Psycopg `~Connection` and `~Cursor` have counterparts `~AsyncConnection` and
`~AsyncCursor` supporting an `asyncio` interface.
not quite. Please note that `~Connection.connect()` and `~Connection.cursor()`
*don't return a context*: they are both factory methods which return *an
object which can be used as a context*. That's because there are several use
-cases where it's useful to handle the object manually and `!close()` them when
-required.
+cases where it's useful to handle the objects manually and only `!close()` them
+when required.
As a consequence you cannot use `!async with connect()`: you have to do it in
two steps instead, as in
async with aconn.cursor() as cur:
await cur.execute(...)
-which can be condensed as:
+which can be condensed into `!async with await`:
.. code:: python
...but no less than that: you still need to do the double async thing.
-The `AsyncConnection.cursor()` function is not marked as `!async` (it never
-performs I/O), so you don't need an `!await` on it and you can use the normal
-`async with` context manager.
-
+Note that the `AsyncConnection.cursor()` function is not an `!async` function
+(it never performs I/O), so you don't need an `!await` on it; as a consequence
+you can use the normal `async with` context manager.
.. index::
The downside is that the server needs to keep track of the partially
processed results, so it uses more memory and resources on the server.
-Psycopg allows the use of server-side cursors using the classes
-`ServerCursor` and `AsyncServerCursor`. They are usually created by passing
-the *name* parameter to the `~Connection.cursor()` method (in `!psycopg2` they
-are also called *named cursors*). The use of these classes is similar to their
-client-side counterparts: their interface is the same, but behind the scene
-they send commands to control the state of the cursor in the server (for
-instance when fetching new records or when moving using `~Cursor.scroll()`).
+Psycopg allows the use of server-side cursors using the classes `ServerCursor`
+and `AsyncServerCursor`. They are usually created by passing the *name*
+parameter to the `~Connection.cursor()` method (reason for which, in
+`!psycopg2`, they are usually called *named cursors*). The use of these classes
+is similar to their client-side counterparts: their interface is the same, but
+behind the scene they send commands to control the state of the cursor on the
+server (for instance when fetching new records or when moving using
+`~Cursor.scroll()`).
Using a server-side cursor it is possible to process datasets larger than what
would fit in the client memory. However for small queries they are less
"Stealing" an existing cursor
-----------------------------
-A Psycopg `ServerCursor` can be also used to consume a cursor that the
-:sql:`DECLARE` generated by its `~ServerCursor.execute()` method can produce.
+A Psycopg `ServerCursor` can be also used to consume a cursor which was
+created in other ways than the :sql:`DECLARE` that `ServerCursor.execute()`
+runs behind the scene.
-For instance if you have a PL/pgSQL function creating a cursor:
+For instance if you have a `PL/pgSQL function returning a cursor`__:
+
+.. __: https://www.postgresql.org/docs/current/plpgsql-cursors.html
.. code:: postgres
END;
$$ LANGUAGE plpgsql;
-you can run a one-off command (e.g. using `Connection.execute()`) to call it
-and create the server cursor:
+you can run a one-off command in the same connection to call it (e.g. using
+`Connection.execute()`) in order to create the cursor on the server:
.. code:: python
conn.execute("SELECT reffunc('curname')")
-then create a server-side cursor with the same name and call directly the
-fetch methods, omitting to call `~ServerCursor.execute()` before:
+after which you can create a server-side cursor declared by the same name, and
+call directly the fetch methods, skipping the `~ServerCursor.execute()` call:
.. code:: python
projects / thirdparty / psycopg.git / commitdiff
