2010-02-09 07:58:28 +03:00
|
|
|
The ``cursor`` class
|
|
|
|
====================
|
|
|
|
|
|
|
|
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
|
|
|
|
|
2010-02-13 19:06:39 +03:00
|
|
|
.. testsetup:: *
|
|
|
|
|
|
|
|
from StringIO import StringIO
|
|
|
|
import sys
|
|
|
|
|
|
|
|
create_test_table()
|
|
|
|
|
|
|
|
# initial data
|
|
|
|
cur.executemany("INSERT INTO test (num, data) VALUES (%s, %s)",
|
|
|
|
[(100, "abc'def"), (None, 'dada'), (42, 'bar')])
|
|
|
|
conn.commit()
|
|
|
|
|
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. class:: cursor
|
|
|
|
|
|
|
|
Allows Python code to execute PostgreSQL command in a database session.
|
2010-02-26 03:17:52 +03:00
|
|
|
Cursors are created by the `connection.cursor()` method: they are
|
2010-02-11 06:15:14 +03:00
|
|
|
bound to the connection for the entire lifetime and all the commands are
|
|
|
|
executed in the context of the database session wrapped by the connection.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
Cursors created from the same connection are not isolated, i.e., any
|
|
|
|
changes done to the database by a cursor are immediately visible by the
|
|
|
|
other cursors. Cursors created from different connections can or can not
|
2010-02-11 06:15:14 +03:00
|
|
|
be isolated, depending on the connections' :ref:`isolation level
|
2010-02-26 03:17:52 +03:00
|
|
|
<transactions-control>`. See also `~connection.rollback()` and
|
|
|
|
`~connection.commit()` methods.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
Cursors are *not* thread safe: a multithread application can create
|
2010-02-18 04:08:44 +03:00
|
|
|
many cursors from the same connection and should use each cursor from
|
2010-02-09 07:58:28 +03:00
|
|
|
a single thread. See :ref:`thread-safety` for details.
|
|
|
|
|
|
|
|
|
|
|
|
.. attribute:: description
|
|
|
|
|
|
|
|
This read-only attribute is a sequence of 7-item sequences.
|
|
|
|
|
2011-02-19 03:05:43 +03:00
|
|
|
Each of these sequences is a named tuple (a regular tuple if
|
2011-02-19 19:16:28 +03:00
|
|
|
:func:`collections.namedtuple` is not available) containing information
|
2011-02-19 03:05:43 +03:00
|
|
|
describing one result column:
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-02-17 16:38:18 +03:00
|
|
|
0. `!name`: the name of the column returned.
|
|
|
|
1. `!type_code`: the PostgreSQL OID of the column. You can use the
|
|
|
|
|pg_type|_ system table to get more informations about the type.
|
|
|
|
This is the value used by Psycopg to decide what Python type use
|
|
|
|
to represent the value. See also
|
|
|
|
:ref:`type-casting-from-sql-to-python`.
|
|
|
|
2. `!display_size`: the actual length of the column in bytes.
|
|
|
|
Obtaining this value is computationally intensive, so it is
|
|
|
|
always `!None` unless the :envvar:`PSYCOPG_DISPLAY_SIZE` parameter
|
|
|
|
is set at compile time. See also PQgetlength_.
|
|
|
|
3. `!internal_size`: the size in bytes of the column associated to
|
2011-02-19 03:05:43 +03:00
|
|
|
this column on the server. Set to a negative value for
|
2011-02-17 16:38:18 +03:00
|
|
|
variable-size types See also PQfsize_.
|
|
|
|
4. `!precision`: total number of significant digits in columns of
|
|
|
|
type |NUMERIC|_. `!None` for other types.
|
2011-02-19 03:05:43 +03:00
|
|
|
5. `!scale`: count of decimal digits in the fractional part in
|
2011-02-17 16:38:18 +03:00
|
|
|
columns of type |NUMERIC|. `!None` for other types.
|
|
|
|
6. `!null_ok`: always `!None` as not easy to retrieve from the libpq.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-02-19 19:16:28 +03:00
|
|
|
This attribute will be `!None` for operations that do not return rows
|
2010-02-09 07:58:28 +03:00
|
|
|
or if the cursor has not had an operation invoked via the
|
|
|
|
|execute*|_ methods yet.
|
|
|
|
|
2011-02-17 16:38:18 +03:00
|
|
|
.. |pg_type| replace:: :sql:`pg_type`
|
2012-02-28 20:28:07 +04:00
|
|
|
.. _pg_type: http://www.postgresql.org/docs/current/static/catalog-pg-type.html
|
|
|
|
.. _PQgetlength: http://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQGETLENGTH
|
|
|
|
.. _PQfsize: http://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQFSIZE
|
|
|
|
.. _NUMERIC: http://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL
|
2011-02-17 16:38:18 +03:00
|
|
|
.. |NUMERIC| replace:: :sql:`NUMERIC`
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2011-02-19 03:05:43 +03:00
|
|
|
.. versionchanged:: 2.4
|
|
|
|
if possible, columns descriptions are named tuple instead of
|
|
|
|
regular tuples.
|
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. method:: close()
|
|
|
|
|
2011-02-19 19:16:28 +03:00
|
|
|
Close the cursor now (rather than whenever `del` is executed).
|
|
|
|
The cursor will be unusable from this point forward; an
|
2010-02-26 03:17:52 +03:00
|
|
|
`~psycopg2.InterfaceError` will be raised if any operation is
|
2010-02-11 06:15:14 +03:00
|
|
|
attempted with the cursor.
|
2012-12-03 07:18:51 +04:00
|
|
|
|
|
|
|
.. versionchanged:: 2.5 if the cursor is used in a ``with`` statement,
|
|
|
|
the method is automatically called at the end of the ``with``
|
|
|
|
block.
|
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
.. attribute:: closed
|
|
|
|
|
|
|
|
Read-only boolean attribute: specifies if the cursor is closed
|
2011-02-19 19:16:28 +03:00
|
|
|
(`!True`) or not (`!False`).
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
.. extension::
|
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
The `closed` attribute is a Psycopg extension to the
|
2010-02-10 02:09:48 +03:00
|
|
|
|DBAPI|.
|
|
|
|
|
2010-02-13 08:49:34 +03:00
|
|
|
.. versionadded:: 2.0.7
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. attribute:: connection
|
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
Read-only attribute returning a reference to the `connection`
|
2010-02-09 07:58:28 +03:00
|
|
|
object on which the cursor was created.
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. attribute:: name
|
|
|
|
|
|
|
|
Read-only attribute containing the name of the cursor if it was
|
2011-02-19 19:16:28 +03:00
|
|
|
creates as named cursor by `connection.cursor()`, or `!None` if
|
2010-02-09 07:58:28 +03:00
|
|
|
it is a client side cursor. See :ref:`server-side-cursors`.
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
.. extension::
|
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
The `name` attribute is a Psycopg extension to the |DBAPI|.
|
2010-02-10 02:09:48 +03:00
|
|
|
|
|
|
|
|
2012-08-15 14:26:45 +04:00
|
|
|
.. 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.
|
|
|
|
|
2012-12-02 16:04:24 +04:00
|
|
|
.. versionadded:: 2.5
|
2012-08-15 14:26:45 +04:00
|
|
|
|
|
|
|
.. extension::
|
|
|
|
|
|
|
|
The `scrollable` attribute is a Psycopg extension to the |DBAPI|.
|
|
|
|
|
|
|
|
|
2011-08-10 21:21:12 +04:00
|
|
|
.. attribute:: withhold
|
2012-08-15 14:26:45 +04:00
|
|
|
|
2011-08-10 21:21:12 +04:00
|
|
|
Read/write attribute: specifies if a named cursor lifetime should
|
|
|
|
extend outside of the current transaction, i.e., it is possible to
|
2012-08-15 14:26:45 +04:00
|
|
|
fetch from the cursor even after a `connection.commit()` (but not after
|
2011-08-10 21:21:12 +04:00
|
|
|
a `connection.rollback()`). See :ref:`server-side-cursors`
|
|
|
|
|
2012-08-15 14:26:45 +04:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
set the value before calling `~cursor.execute()` or use the
|
|
|
|
`connection.cursor()` *withhold* parameter, otherwise the value
|
|
|
|
will have no effect.
|
|
|
|
|
2011-08-10 21:21:12 +04:00
|
|
|
.. versionadded:: 2.4.3
|
2012-08-15 14:26:45 +04:00
|
|
|
|
2011-08-10 21:21:12 +04:00
|
|
|
.. extension::
|
|
|
|
|
2011-10-06 21:38:30 +04:00
|
|
|
The `withhold` attribute is a Psycopg extension to the |DBAPI|.
|
2012-08-15 14:26:45 +04:00
|
|
|
|
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
.. |execute*| replace:: `execute*()`
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
.. _execute*:
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
.. rubric:: Commands execution methods
|
|
|
|
|
|
|
|
|
2017-02-08 13:15:16 +03:00
|
|
|
.. method:: execute(query, vars=None)
|
2017-02-01 04:59:47 +03:00
|
|
|
|
2017-02-08 13:15:16 +03:00
|
|
|
Execute a database operation (query or command).
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
Parameters may be provided as sequence or mapping and will be bound to
|
|
|
|
variables in the operation. Variables are specified either with
|
2010-02-11 06:15:14 +03:00
|
|
|
positional (``%s``) or named (:samp:`%({name})s`) placeholders. See
|
2010-02-09 07:58:28 +03:00
|
|
|
:ref:`query-parameters`.
|
2017-02-01 04:59:47 +03:00
|
|
|
|
2011-02-19 19:16:28 +03:00
|
|
|
The method returns `!None`. If a query was executed, the returned
|
2010-02-09 07:58:28 +03:00
|
|
|
values can be retrieved using |fetch*|_ methods.
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2017-02-08 13:15:16 +03:00
|
|
|
.. method:: executemany(query, vars_list)
|
2017-02-01 04:59:47 +03:00
|
|
|
|
2017-02-08 13:15:16 +03:00
|
|
|
Execute a database operation (query or command) against all parameter
|
2017-02-08 17:01:57 +03:00
|
|
|
tuples or mappings found in the sequence *vars_list*.
|
2017-02-01 04:59:47 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
The function is mostly useful for commands that update the database:
|
|
|
|
any result set returned by the query is discarded.
|
2017-02-01 04:59:47 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
Parameters are bounded to the query using the same rules described in
|
2010-02-26 03:17:52 +03:00
|
|
|
the `~cursor.execute()` method.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2017-02-01 04:59:47 +03:00
|
|
|
.. warning::
|
|
|
|
In its current implementation this method is not faster than
|
|
|
|
executing `~cursor.execute()` in a loop. For better performance
|
|
|
|
you can use the functions described in :ref:`fast-exec`.
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-04-08 16:22:55 +04:00
|
|
|
.. method:: callproc(procname [, parameters])
|
2017-02-01 04:59:47 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
Call a stored database procedure with the given name. The sequence of
|
|
|
|
parameters must contain one entry for each argument that the procedure
|
2014-05-31 04:34:19 +04:00
|
|
|
expects. Overloaded procedures are supported. Named parameters can be
|
2016-12-26 05:39:28 +03:00
|
|
|
used by supplying the parameters as a dictionary.
|
2014-05-31 04:34:19 +04:00
|
|
|
|
|
|
|
This function is, at present, not DBAPI-compliant. The return value is
|
|
|
|
supposed to consist of the sequence of parameters with modified output
|
|
|
|
and input/output parameters. In future versions, the DBAPI-compliant
|
|
|
|
return value may be implemented, but for now the function returns None.
|
|
|
|
|
|
|
|
The procedure may provide a result set as output. This is then made
|
|
|
|
available through the standard |fetch*|_ methods.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2016-12-26 05:39:28 +03:00
|
|
|
.. versionchanged:: 2.7
|
|
|
|
added support for named arguments.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-01-02 00:55:10 +03:00
|
|
|
.. method:: mogrify(operation [, parameters])
|
|
|
|
|
|
|
|
Return a query string after arguments binding. The string returned is
|
|
|
|
exactly the one that would be sent to the database running the
|
|
|
|
`~cursor.execute()` method or similar.
|
|
|
|
|
2014-04-03 05:46:13 +04:00
|
|
|
The returned string is always a bytes string.
|
|
|
|
|
2011-01-02 00:55:10 +03:00
|
|
|
>>> cur.mogrify("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
|
|
|
|
"INSERT INTO test (num, data) VALUES (42, E'bar')"
|
|
|
|
|
|
|
|
.. extension::
|
|
|
|
|
|
|
|
The `mogrify()` method is a Psycopg extension to the |DBAPI|.
|
|
|
|
|
2011-02-19 03:44:24 +03:00
|
|
|
.. method:: setinputsizes(sizes)
|
|
|
|
|
|
|
|
This method is exposed in compliance with the |DBAPI|. It currently
|
|
|
|
does nothing but it is safe to call it.
|
2011-01-02 00:55:10 +03:00
|
|
|
|
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
.. |fetch*| replace:: `!fetch*()`
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
.. _fetch*:
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
.. rubric:: Results retrieval methods
|
|
|
|
|
|
|
|
|
2010-02-09 16:33:31 +03:00
|
|
|
The following methods are used to read data from the database after an
|
2010-02-26 03:17:52 +03:00
|
|
|
`~cursor.execute()` call.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-03-03 20:43:24 +03:00
|
|
|
.. _cursor-iterable:
|
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. note::
|
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
`cursor` objects are iterable, so, instead of calling
|
|
|
|
explicitly `~cursor.fetchone()` in a loop, the object itself can
|
2010-02-13 19:06:39 +03:00
|
|
|
be used:
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
>>> cur.execute("SELECT * FROM test;")
|
|
|
|
>>> for record in cur:
|
|
|
|
... print record
|
|
|
|
...
|
|
|
|
(1, 100, "abc'def")
|
|
|
|
(2, None, 'dada')
|
2010-02-13 19:06:39 +03:00
|
|
|
(3, 42, 'bar')
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-02-15 14:00:08 +03:00
|
|
|
.. versionchanged:: 2.4
|
2011-02-04 19:29:29 +03:00
|
|
|
iterating over a :ref:`named cursor <server-side-cursors>`
|
2011-02-17 15:29:07 +03:00
|
|
|
fetches `~cursor.itersize` records at time from the backend.
|
2011-02-04 19:29:29 +03:00
|
|
|
Previously only one record was fetched per roundtrip, resulting
|
2011-02-17 15:29:07 +03:00
|
|
|
in a large overhead.
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. method:: fetchone()
|
|
|
|
|
|
|
|
Fetch the next row of a query result set, returning a single tuple,
|
2011-02-19 19:16:28 +03:00
|
|
|
or `!None` when no more data is available:
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-13 19:06:39 +03:00
|
|
|
>>> cur.execute("SELECT * FROM test WHERE id = %s", (3,))
|
2010-02-09 07:58:28 +03:00
|
|
|
>>> cur.fetchone()
|
2010-02-13 19:06:39 +03:00
|
|
|
(3, 42, 'bar')
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
A `~psycopg2.ProgrammingError` is raised if the previous call
|
2010-02-09 07:58:28 +03:00
|
|
|
to |execute*|_ did not produce any result set or no call was issued
|
|
|
|
yet.
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. method:: fetchmany([size=cursor.arraysize])
|
|
|
|
|
|
|
|
Fetch the next set of rows of a query result, returning a list of
|
|
|
|
tuples. An empty list is returned when no more rows are available.
|
|
|
|
|
|
|
|
The number of rows to fetch per call is specified by the parameter.
|
2010-02-26 03:17:52 +03:00
|
|
|
If it is not given, the cursor's `~cursor.arraysize` determines
|
2010-02-11 06:15:14 +03:00
|
|
|
the number of rows to be fetched. The method should try to fetch as
|
|
|
|
many rows as indicated by the size parameter. If this is not possible
|
|
|
|
due to the specified number of rows not being available, fewer rows
|
2010-02-13 19:06:39 +03:00
|
|
|
may be returned:
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
>>> cur.execute("SELECT * FROM test;")
|
|
|
|
>>> cur.fetchmany(2)
|
|
|
|
[(1, 100, "abc'def"), (2, None, 'dada')]
|
|
|
|
>>> cur.fetchmany(2)
|
2010-02-13 19:06:39 +03:00
|
|
|
[(3, 42, 'bar')]
|
2010-02-09 07:58:28 +03:00
|
|
|
>>> cur.fetchmany(2)
|
|
|
|
[]
|
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
A `~psycopg2.ProgrammingError` is raised if the previous call to
|
2010-02-11 06:15:14 +03:00
|
|
|
|execute*|_ did not produce any result set or no call was issued yet.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
Note there are performance considerations involved with the size
|
|
|
|
parameter. For optimal performance, it is usually best to use the
|
2010-02-26 03:17:52 +03:00
|
|
|
`~cursor.arraysize` attribute. If the size parameter is used,
|
2010-02-11 06:15:14 +03:00
|
|
|
then it is best for it to retain the same value from one
|
2010-02-26 03:17:52 +03:00
|
|
|
`fetchmany()` call to the next.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. method:: fetchall()
|
|
|
|
|
|
|
|
Fetch all (remaining) rows of a query result, returning them as a list
|
2010-02-11 06:15:14 +03:00
|
|
|
of tuples. An empty list is returned if there is no more record to
|
|
|
|
fetch.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
>>> cur.execute("SELECT * FROM test;")
|
|
|
|
>>> cur.fetchall()
|
2010-02-13 19:06:39 +03:00
|
|
|
[(1, 100, "abc'def"), (2, None, 'dada'), (3, 42, 'bar')]
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
A `~psycopg2.ProgrammingError` is raised if the previous call to
|
2010-02-11 06:15:14 +03:00
|
|
|
|execute*|_ did not produce any result set or no call was issued yet.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
.. method:: scroll(value [, mode='relative'])
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
Scroll the cursor in the result set to a new position according
|
|
|
|
to mode.
|
|
|
|
|
2010-02-18 04:08:44 +03:00
|
|
|
If `mode` is ``relative`` (default), value is taken as offset to
|
2010-02-09 07:58:28 +03:00
|
|
|
the current position in the result set, if set to ``absolute``,
|
|
|
|
value states an absolute target position.
|
|
|
|
|
|
|
|
If the scroll operation would leave the result set, a
|
2010-02-26 03:17:52 +03:00
|
|
|
`~psycopg2.ProgrammingError` is raised and the cursor position is
|
2010-02-11 06:15:14 +03:00
|
|
|
not changed.
|
|
|
|
|
|
|
|
.. note::
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
According to the |DBAPI|_, the exception raised for a cursor out
|
2010-02-26 03:17:52 +03:00
|
|
|
of bound should have been `!IndexError`. The best option is
|
2010-02-15 06:08:51 +03:00
|
|
|
probably to catch both exceptions in your code::
|
2010-02-13 00:52:25 +03:00
|
|
|
|
|
|
|
try:
|
|
|
|
cur.scroll(1000 * 1000)
|
|
|
|
except (ProgrammingError, IndexError), exc:
|
|
|
|
deal_with_it(exc)
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2013-10-16 22:08:45 +04:00
|
|
|
The method can be used both for client-side cursors and
|
|
|
|
:ref:`server-side cursors <server-side-cursors>`. Server-side cursors
|
|
|
|
can usually scroll backwards only if declared `~cursor.scrollable`.
|
|
|
|
Moving out-of-bound in a server-side cursor doesn't result in an
|
|
|
|
exception, if the backend doesn't raise any (Postgres doesn't tell us
|
|
|
|
in a reliable way if we went out of bound).
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. attribute:: arraysize
|
|
|
|
|
|
|
|
This read/write attribute specifies the number of rows to fetch at a
|
2010-02-26 03:17:52 +03:00
|
|
|
time with `~cursor.fetchmany()`. It defaults to 1 meaning to fetch
|
2010-02-11 06:15:14 +03:00
|
|
|
a single row at a time.
|
2011-02-04 19:29:29 +03:00
|
|
|
|
|
|
|
|
2011-02-17 15:29:07 +03:00
|
|
|
.. attribute:: itersize
|
|
|
|
|
|
|
|
Read/write attribute specifying the number of rows to fetch from the
|
|
|
|
backend at each network roundtrip during :ref:`iteration
|
|
|
|
<cursor-iterable>` on a :ref:`named cursor <server-side-cursors>`. The
|
|
|
|
default is 2000.
|
|
|
|
|
|
|
|
.. versionadded:: 2.4
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-02-17 15:29:07 +03:00
|
|
|
.. extension::
|
|
|
|
|
|
|
|
The `itersize` attribute is a Psycopg extension to the |DBAPI|.
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. attribute:: rowcount
|
|
|
|
|
|
|
|
This read-only attribute specifies the number of rows that the last
|
2010-02-11 06:15:14 +03:00
|
|
|
|execute*|_ produced (for :abbr:`DQL (Data Query Language)` statements
|
|
|
|
like :sql:`SELECT`) or affected (for
|
|
|
|
:abbr:`DML (Data Manipulation Language)` statements like :sql:`UPDATE`
|
|
|
|
or :sql:`INSERT`).
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
The attribute is -1 in case no |execute*| has been performed on
|
2010-02-09 16:33:31 +03:00
|
|
|
the cursor or the row count of the last operation if it can't be
|
2010-02-09 07:58:28 +03:00
|
|
|
determined by the interface.
|
|
|
|
|
|
|
|
.. note::
|
2010-02-10 00:31:40 +03:00
|
|
|
The |DBAPI|_ interface reserves to redefine the latter case to
|
2011-02-19 19:16:28 +03:00
|
|
|
have the object return `!None` instead of -1 in future versions
|
2010-02-09 07:58:28 +03:00
|
|
|
of the specification.
|
2010-02-10 02:09:48 +03:00
|
|
|
|
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. attribute:: rownumber
|
|
|
|
|
|
|
|
This read-only attribute provides the current 0-based index of the
|
2011-02-19 19:16:28 +03:00
|
|
|
cursor in the result set or `!None` if the index cannot be
|
2010-02-09 07:58:28 +03:00
|
|
|
determined.
|
|
|
|
|
|
|
|
The index can be seen as index of the cursor in a sequence (the result
|
|
|
|
set). The next fetch operation will fetch the row indexed by
|
2010-02-26 03:17:52 +03:00
|
|
|
`rownumber` in that sequence.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-02-09 07:58:28 +03:00
|
|
|
.. index:: oid
|
|
|
|
|
|
|
|
.. attribute:: lastrowid
|
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
This read-only attribute provides the OID of the last row inserted
|
|
|
|
by the cursor. If the table wasn't created with OID support or the
|
2010-02-09 07:58:28 +03:00
|
|
|
last operation is not a single record insert, the attribute is set to
|
2011-02-19 19:16:28 +03:00
|
|
|
`!None`.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-02-19 03:52:26 +03:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
PostgreSQL currently advices to not create OIDs on the tables and
|
|
|
|
the default for |CREATE-TABLE|__ is to not support them. The
|
|
|
|
|INSERT-RETURNING|__ syntax available from PostgreSQL 8.3 allows
|
|
|
|
more flexibility.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
.. |CREATE-TABLE| replace:: :sql:`CREATE TABLE`
|
2012-02-28 20:28:07 +04:00
|
|
|
.. __: http://www.postgresql.org/docs/current/static/sql-createtable.html
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
.. |INSERT-RETURNING| replace:: :sql:`INSERT ... RETURNING`
|
2012-02-28 20:28:07 +04:00
|
|
|
.. __: http://www.postgresql.org/docs/current/static/sql-insert.html
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
.. attribute:: query
|
|
|
|
|
|
|
|
Read-only attribute containing the body of the last query sent to the
|
2014-04-03 05:46:13 +04:00
|
|
|
backend (including bound arguments) as bytes string. `!None` if no
|
|
|
|
query has been executed yet:
|
2010-02-10 02:09:48 +03:00
|
|
|
|
|
|
|
>>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
|
2014-04-03 05:46:13 +04:00
|
|
|
>>> cur.query
|
2010-02-10 02:09:48 +03:00
|
|
|
"INSERT INTO test (num, data) VALUES (42, E'bar')"
|
|
|
|
|
|
|
|
.. extension::
|
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
The `query` attribute is a Psycopg extension to the |DBAPI|.
|
2010-02-10 02:09:48 +03:00
|
|
|
|
|
|
|
|
|
|
|
.. attribute:: statusmessage
|
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
Read-only attribute containing the message returned by the last
|
2010-02-13 19:06:39 +03:00
|
|
|
command:
|
2010-02-10 02:09:48 +03:00
|
|
|
|
|
|
|
>>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
|
|
|
|
>>> cur.statusmessage
|
|
|
|
'INSERT 0 1'
|
|
|
|
|
|
|
|
.. extension::
|
|
|
|
|
2010-02-26 03:17:52 +03:00
|
|
|
The `statusmessage` attribute is a Psycopg extension to the
|
2010-02-10 02:09:48 +03:00
|
|
|
|DBAPI|.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
|
|
|
|
2011-02-19 03:44:24 +03:00
|
|
|
.. method:: cast(oid, s)
|
|
|
|
|
|
|
|
Convert a value from the PostgreSQL string representation to a Python
|
|
|
|
object.
|
|
|
|
|
|
|
|
Use the most specific of the typecasters registered by
|
|
|
|
`~psycopg2.extensions.register_type()`.
|
|
|
|
|
|
|
|
.. versionadded:: 2.4
|
|
|
|
|
|
|
|
.. extension::
|
|
|
|
|
|
|
|
The `cast()` method is a Psycopg extension to the |DBAPI|.
|
|
|
|
|
|
|
|
|
2010-04-08 16:22:55 +04:00
|
|
|
.. attribute:: tzinfo_factory
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2010-04-08 16:22:55 +04:00
|
|
|
The time zone factory used to handle data types such as
|
2011-02-19 19:16:28 +03:00
|
|
|
:sql:`TIMESTAMP WITH TIME ZONE`. It should be a `~datetime.tzinfo`
|
|
|
|
object. A few implementations are available in the `psycopg2.tz`
|
|
|
|
module.
|
2010-02-10 02:09:48 +03:00
|
|
|
|
|
|
|
|
2011-02-19 03:44:24 +03:00
|
|
|
.. method:: nextset()
|
|
|
|
|
|
|
|
This method is not supported (PostgreSQL does not have multiple data
|
|
|
|
sets) and will raise a `~psycopg2.NotSupportedError` exception.
|
|
|
|
|
|
|
|
|
|
|
|
.. method:: setoutputsize(size [, column])
|
|
|
|
|
|
|
|
This method is exposed in compliance with the |DBAPI|. It currently
|
|
|
|
does nothing but it is safe to call it.
|
|
|
|
|
|
|
|
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
.. rubric:: COPY-related methods
|
|
|
|
|
2016-07-01 03:39:10 +03:00
|
|
|
Efficiently copy data from file-like objects to the database and back. See
|
|
|
|
:ref:`copy` for an overview.
|
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
.. extension::
|
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
The :sql:`COPY` command is a PostgreSQL extension to the SQL standard.
|
|
|
|
As such, its support is a Psycopg extension to the |DBAPI|.
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2011-10-20 14:07:24 +04:00
|
|
|
.. method:: copy_from(file, table, sep='\\t', null='\\\\N', size=8192, columns=None)
|
2011-06-07 13:48:26 +04:00
|
|
|
|
2011-02-19 19:16:28 +03:00
|
|
|
Read data *from* the file-like object *file* appending them to
|
2016-07-01 03:39:10 +03:00
|
|
|
the table named *table*.
|
2010-02-10 03:10:51 +03:00
|
|
|
|
2011-06-07 13:48:26 +04:00
|
|
|
:param file: file-like object to read data from. It must have both
|
|
|
|
`!read()` and `!readline()` methods.
|
|
|
|
:param table: name of the table to copy data into.
|
|
|
|
:param sep: columns separator expected in the file. Defaults to a tab.
|
|
|
|
:param null: textual representation of :sql:`NULL` in the file.
|
2012-02-23 18:28:11 +04:00
|
|
|
The default is the two characters string ``\N``.
|
2011-06-07 13:48:26 +04:00
|
|
|
:param size: size of the buffer used to read from the file.
|
|
|
|
:param columns: iterable with name of the columns to import.
|
|
|
|
The length and types should match the content of the file to read.
|
|
|
|
If not specified, it is assumed that the entire table matches the
|
|
|
|
file structure.
|
2010-02-10 03:10:51 +03:00
|
|
|
|
2011-06-07 13:48:26 +04:00
|
|
|
Example::
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-09 19:30:52 +03:00
|
|
|
>>> f = StringIO("42\tfoo\n74\tbar\n")
|
|
|
|
>>> cur.copy_from(f, 'test', columns=('num', 'data'))
|
|
|
|
>>> cur.execute("select * from test where id > 5;")
|
|
|
|
>>> cur.fetchall()
|
2010-02-13 19:06:39 +03:00
|
|
|
[(6, 42, 'foo'), (7, 74, 'bar')]
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2015-05-03 12:22:14 +03:00
|
|
|
.. note:: the name of the table is not quoted: if the table name
|
|
|
|
contains uppercase letters or special characters it must be quoted
|
|
|
|
with double quotes::
|
|
|
|
|
|
|
|
cur.copy_from(f, '"TABLE"')
|
|
|
|
|
|
|
|
|
2010-02-09 19:30:52 +03:00
|
|
|
.. versionchanged:: 2.0.6
|
2011-02-19 19:16:28 +03:00
|
|
|
added the *columns* parameter.
|
2010-02-09 19:30:52 +03:00
|
|
|
|
2011-02-19 19:16:28 +03:00
|
|
|
.. versionchanged:: 2.4
|
|
|
|
data read from files implementing the `io.TextIOBase` interface
|
|
|
|
are encoded in the connection `~connection.encoding` when sent to
|
|
|
|
the backend.
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2011-10-20 14:07:24 +04:00
|
|
|
.. method:: copy_to(file, table, sep='\\t', null='\\\\N', columns=None)
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-02-19 19:16:28 +03:00
|
|
|
Write the content of the table named *table* *to* the file-like
|
2011-06-07 13:48:26 +04:00
|
|
|
object *file*. See :ref:`copy` for an overview.
|
2010-02-09 19:30:52 +03:00
|
|
|
|
2011-06-07 13:48:26 +04:00
|
|
|
:param file: file-like object to write data into. It must have a
|
|
|
|
`!write()` method.
|
|
|
|
:param table: name of the table to copy data from.
|
|
|
|
:param sep: columns separator expected in the file. Defaults to a tab.
|
|
|
|
:param null: textual representation of :sql:`NULL` in the file.
|
2012-02-23 18:28:11 +04:00
|
|
|
The default is the two characters string ``\N``.
|
2011-06-07 13:48:26 +04:00
|
|
|
:param columns: iterable with name of the columns to export.
|
|
|
|
If not specified, export all the columns.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-06-07 13:48:26 +04:00
|
|
|
Example::
|
2010-02-10 03:10:51 +03:00
|
|
|
|
|
|
|
>>> cur.copy_to(sys.stdout, 'test', sep="|")
|
|
|
|
1|100|abc'def
|
|
|
|
2|\N|dada
|
2010-02-13 19:06:39 +03:00
|
|
|
...
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2015-05-03 12:22:14 +03:00
|
|
|
.. note:: the name of the table is not quoted: if the table name
|
|
|
|
contains uppercase letters or special characters it must be quoted
|
|
|
|
with double quotes::
|
|
|
|
|
|
|
|
cur.copy_to(f, '"TABLE"')
|
|
|
|
|
2010-02-09 19:30:52 +03:00
|
|
|
.. versionchanged:: 2.0.6
|
2011-02-19 19:16:28 +03:00
|
|
|
added the *columns* parameter.
|
|
|
|
|
|
|
|
.. versionchanged:: 2.4
|
|
|
|
data sent to files implementing the `io.TextIOBase` interface
|
|
|
|
are decoded in the connection `~connection.encoding` when read
|
|
|
|
from the backend.
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-10 02:09:48 +03:00
|
|
|
|
2011-06-07 13:48:26 +04:00
|
|
|
.. method:: copy_expert(sql, file, size=8192)
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
Submit a user-composed :sql:`COPY` statement. The method is useful to
|
2010-02-09 19:30:52 +03:00
|
|
|
handle all the parameters that PostgreSQL makes available (see
|
|
|
|
|COPY|__ command documentation).
|
|
|
|
|
2011-06-07 13:48:26 +04:00
|
|
|
:param sql: the :sql:`COPY` statement to execute.
|
2012-10-15 03:38:28 +04:00
|
|
|
:param file: a file-like object to read or write (according to *sql*).
|
2011-06-07 13:48:26 +04:00
|
|
|
:param size: size of the read buffer to be used in :sql:`COPY FROM`.
|
|
|
|
|
2012-10-15 03:38:28 +04:00
|
|
|
The *sql* statement should be in the form :samp:`COPY {table} TO
|
|
|
|
STDOUT` to export :samp:`{table}` to the *file* object passed as
|
|
|
|
argument or :samp:`COPY {table} FROM STDIN` to import the content of
|
2017-03-16 03:12:13 +03:00
|
|
|
the *file* object into :samp:`{table}`. If you need to compose a
|
|
|
|
:sql:`COPY` statement dynamically (because table, fields, or query
|
|
|
|
parameters are in Python variables) you may use the objects provided
|
|
|
|
by the `psycopg2.sql` module.
|
2012-10-15 03:38:28 +04:00
|
|
|
|
|
|
|
*file* must be a readable file-like object (as required by
|
|
|
|
`~cursor.copy_from()`) for *sql* statement :sql:`COPY ... FROM STDIN`
|
|
|
|
or a writable one (as required by `~cursor.copy_to()`) for :sql:`COPY
|
|
|
|
... TO STDOUT`.
|
|
|
|
|
2011-06-07 13:48:26 +04:00
|
|
|
Example:
|
2010-02-10 03:10:51 +03:00
|
|
|
|
2010-02-09 19:30:52 +03:00
|
|
|
>>> cur.copy_expert("COPY test TO STDOUT WITH CSV HEADER", sys.stdout)
|
|
|
|
id,num,data
|
|
|
|
1,100,abc'def
|
|
|
|
2,,dada
|
2010-02-13 19:06:39 +03:00
|
|
|
...
|
2010-02-09 19:30:52 +03:00
|
|
|
|
2010-02-11 06:15:14 +03:00
|
|
|
.. |COPY| replace:: :sql:`COPY`
|
2012-02-28 20:28:07 +04:00
|
|
|
.. __: http://www.postgresql.org/docs/current/static/sql-copy.html
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2010-02-09 19:30:52 +03:00
|
|
|
.. versionadded:: 2.0.6
|
2010-02-09 07:58:28 +03:00
|
|
|
|
2011-02-19 19:16:28 +03:00
|
|
|
.. versionchanged:: 2.4
|
|
|
|
files implementing the `io.TextIOBase` interface are dealt with
|
|
|
|
using Unicode data instead of bytes.
|
|
|
|
|
2010-04-20 02:51:42 +04:00
|
|
|
|
|
|
|
.. testcode::
|
|
|
|
:hide:
|
|
|
|
|
|
|
|
conn.rollback()
|