1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
1 |
The ``connection`` class |
2 |
======================== |
|
3 |
||
4 |
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com> |
|
5 |
||
6 |
.. testsetup:: |
|
7 |
||
8 |
from pprint import pprint |
|
9 |
import psycopg2.extensions |
|
10 |
||
11 |
drop_test_table('foo') |
|
12 |
||
13 |
.. class:: connection |
|
14 |
||
15 |
Handles the connection to a PostgreSQL database instance. It encapsulates |
|
16 |
a database session. |
|
17 |
||
18 |
Connections are created using the factory function |
|
19 |
`~psycopg2.connect()`. |
|
20 |
||
21 |
Connections are thread safe and can be shared among many thread. See |
|
22 |
:ref:`thread-safety` for details. |
|
23 |
||
24 |
.. method:: cursor([name] [, cursor_factory]) |
|
25 |
||
26 |
Return a new `cursor` object using the connection. |
|
27 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
28 |
If *name* is specified, the returned cursor will be a :ref:`server |
29 |
side cursor <server-side-cursors>` (also known as *named cursor*). |
|
30 |
Otherwise it will be a regular *client side* cursor. |
|
31 |
||
32 |
The name can be a string not valid as a PostgreSQL identifier: for |
|
33 |
example it may start with a digit and contain non-alphanumeric |
|
34 |
characters and quotes. |
|
35 |
||
36 |
.. versionchanged:: 2.4 |
|
37 |
previously only valid PostgreSQL identifiers were accepted as |
|
38 |
cursor name. |
|
39 |
||
40 |
.. warning:: |
|
41 |
It is unsafe to expose the *name* to an untrusted source, for |
|
42 |
instance you shouldn't allow *name* to be read from a HTML form. |
|
43 |
Consider it as part of the query, not as a query parameter. |
|
44 |
||
45 |
The *cursor_factory* argument can be used to create non-standard |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
46 |
cursors. The class returned should be a subclass of |
47 |
`psycopg2.extensions.cursor`. See :ref:`subclassing-cursor` for |
|
48 |
details. |
|
49 |
||
50 |
.. extension:: |
|
51 |
||
52 |
The `name` and `cursor_factory` parameters are Psycopg |
|
53 |
extensions to the |DBAPI|. |
|
54 |
||
55 |
||
56 |
.. index:: |
|
57 |
pair: Transaction; Commit |
|
58 |
||
59 |
.. method:: commit() |
|
60 |
||
61 |
Commit any pending transaction to the database. Psycopg can be set to |
|
62 |
perform automatic commits at each operation, see |
|
63 |
`~connection.set_isolation_level()`. |
|
64 |
||
65 |
||
66 |
.. index:: |
|
67 |
pair: Transaction; Rollback |
|
68 |
||
69 |
.. method:: rollback() |
|
70 |
||
71 |
Roll back to the start of any pending transaction. Closing a |
|
72 |
connection without committing the changes first will cause an implicit |
|
73 |
rollback to be performed. |
|
74 |
||
75 |
||
76 |
.. method:: close() |
|
77 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
78 |
Close the connection now (rather than whenever `del` is executed). |
79 |
The connection will be unusable from this point forward; an |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
80 |
`~psycopg2.InterfaceError` will be raised if any operation is |
81 |
attempted with the connection. The same applies to all cursor objects |
|
82 |
trying to use the connection. Note that closing a connection without |
|
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
83 |
committing the changes first will cause any pending change to be |
84 |
discarded as if a :sql:`ROLLBACK` was performed (unless a different |
|
85 |
isolation level has been selected: see |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
86 |
`~connection.set_isolation_level()`). |
87 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
88 |
.. index:: |
89 |
single: PgBouncer; unclean server |
|
90 |
||
91 |
.. versionchanged:: 2.2 |
|
92 |
previously an explicit :sql:`ROLLBACK` was issued by Psycopg on |
|
93 |
`!close()`. The command could have been sent to the backend at an |
|
94 |
inappropriate time, so Psycopg currently relies on the backend to |
|
95 |
implicitly discard uncommitted changes. Some middleware are known |
|
96 |
to behave incorrectly though when the connection is closed during |
|
97 |
a transaction (when `~connection.status` is |
|
98 |
`~psycopg2.extensions.STATUS_IN_TRANSACTION`), e.g. PgBouncer_ |
|
99 |
reports an ``unclean server`` and discards the connection. To |
|
100 |
avoid this problem you can ensure to terminate the transaction |
|
101 |
with a `~connection.commit()`/`~connection.rollback()` before |
|
102 |
closing. |
|
103 |
||
104 |
.. _PgBouncer: http://pgbouncer.projects.postgresql.org/ |
|
105 |
||
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
106 |
|
107 |
.. index:: |
|
108 |
single: Exceptions; In the connection class |
|
109 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
110 |
.. rubric:: Exceptions as connection class attributes |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
111 |
|
112 |
The `!connection` also exposes as attributes the same exceptions |
|
113 |
available in the `psycopg2` module. See :ref:`dbapi-exceptions`. |
|
114 |
||
115 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
116 |
|
117 |
.. index:: |
|
118 |
single: Two-phase commit; methods |
|
119 |
||
120 |
.. rubric:: Two-phase commit support methods |
|
121 |
||
122 |
.. versionadded:: 2.3 |
|
123 |
||
124 |
.. seealso:: :ref:`tpc` for an introductory explanation of these methods. |
|
125 |
||
126 |
Note that PostgreSQL supports two-phase commit since release 8.1: these |
|
127 |
methods raise `~psycopg2.NotSupportedError` if used with an older version |
|
128 |
server. |
|
129 |
||
130 |
||
131 |
.. _tpc_methods: |
|
132 |
||
133 |
.. method:: xid(format_id, gtrid, bqual) |
|
134 |
||
135 |
Returns a `~psycopg2.extensions.Xid` instance to be passed to the |
|
136 |
`!tpc_*()` methods of this connection. The argument types and |
|
137 |
constraints are explained in :ref:`tpc`. |
|
138 |
||
139 |
The values passed to the method will be available on the returned |
|
140 |
object as the members `~psycopg2.extensions.Xid.format_id`, |
|
141 |
`~psycopg2.extensions.Xid.gtrid`, `~psycopg2.extensions.Xid.bqual`. |
|
142 |
The object also allows accessing to these members and unpacking as a |
|
143 |
3-items tuple. |
|
144 |
||
145 |
||
146 |
.. method:: tpc_begin(xid) |
|
147 |
||
148 |
Begins a TPC transaction with the given transaction ID *xid*. |
|
149 |
||
150 |
This method should be called outside of a transaction (i.e. nothing |
|
151 |
may have executed since the last `~connection.commit()` or |
|
152 |
`~connection.rollback()` and `connection.status` is |
|
153 |
`~psycopg2.extensions.STATUS_READY`). |
|
154 |
||
155 |
Furthermore, it is an error to call `!commit()` or `!rollback()` |
|
156 |
within the TPC transaction: in this case a `~psycopg2.ProgrammingError` |
|
157 |
is raised. |
|
158 |
||
159 |
The *xid* may be either an object returned by the `~connection.xid()` |
|
160 |
method or a plain string: the latter allows to create a transaction |
|
161 |
using the provided string as PostgreSQL transaction id. See also |
|
162 |
`~connection.tpc_recover()`. |
|
163 |
||
164 |
||
165 |
.. index:: |
|
166 |
pair: Transaction; Prepare |
|
167 |
||
168 |
.. method:: tpc_prepare() |
|
169 |
||
170 |
Performs the first phase of a transaction started with |
|
171 |
`~connection.tpc_begin()`. A `~psycopg2.ProgrammingError` is raised if |
|
172 |
this method is used outside of a TPC transaction. |
|
173 |
||
174 |
After calling `!tpc_prepare()`, no statements can be executed until |
|
175 |
`~connection.tpc_commit()` or `~connection.tpc_rollback()` will be |
|
176 |
called. The `~connection.reset()` method can be used to restore the |
|
177 |
status of the connection to `~psycopg2.extensions.STATUS_READY`: the |
|
178 |
transaction will remain prepared in the database and will be |
|
179 |
possible to finish it with `!tpc_commit(xid)` and |
|
180 |
`!tpc_rollback(xid)`. |
|
181 |
||
182 |
.. seealso:: the |PREPARE TRANSACTION|_ PostgreSQL command. |
|
183 |
||
184 |
.. |PREPARE TRANSACTION| replace:: :sql:`PREPARE TRANSACTION` |
|
185 |
.. _PREPARE TRANSACTION: http://www.postgresql.org/docs/9.0/static/sql-prepare-transaction.html |
|
186 |
||
187 |
||
188 |
.. index:: |
|
189 |
pair: Commit; Prepared |
|
190 |
||
191 |
.. method:: tpc_commit([xid]) |
|
192 |
||
193 |
When called with no arguments, `!tpc_commit()` commits a TPC |
|
194 |
transaction previously prepared with `~connection.tpc_prepare()`. |
|
195 |
||
196 |
If `!tpc_commit()` is called prior to `!tpc_prepare()`, a single phase |
|
197 |
commit is performed. A transaction manager may choose to do this if |
|
198 |
only a single resource is participating in the global transaction. |
|
199 |
||
200 |
When called with a transaction ID *xid*, the database commits |
|
201 |
the given transaction. If an invalid transaction ID is |
|
202 |
provided, a `~psycopg2.ProgrammingError` will be raised. This form |
|
203 |
should be called outside of a transaction, and is intended for use in |
|
204 |
recovery. |
|
205 |
||
206 |
On return, the TPC transaction is ended. |
|
207 |
||
208 |
.. seealso:: the |COMMIT PREPARED|_ PostgreSQL command. |
|
209 |
||
210 |
.. |COMMIT PREPARED| replace:: :sql:`COMMIT PREPARED` |
|
211 |
.. _COMMIT PREPARED: http://www.postgresql.org/docs/9.0/static/sql-commit-prepared.html |
|
212 |
||
213 |
||
214 |
.. index:: |
|
215 |
pair: Rollback; Prepared |
|
216 |
||
217 |
.. method:: tpc_rollback([xid]) |
|
218 |
||
219 |
When called with no arguments, `!tpc_rollback()` rolls back a TPC |
|
220 |
transaction. It may be called before or after |
|
221 |
`~connection.tpc_prepare()`. |
|
222 |
||
223 |
When called with a transaction ID *xid*, it rolls back the given |
|
224 |
transaction. If an invalid transaction ID is provided, a |
|
225 |
`~psycopg2.ProgrammingError` is raised. This form should be called |
|
226 |
outside of a transaction, and is intended for use in recovery. |
|
227 |
||
228 |
On return, the TPC transaction is ended. |
|
229 |
||
230 |
.. seealso:: the |ROLLBACK PREPARED|_ PostgreSQL command. |
|
231 |
||
232 |
.. |ROLLBACK PREPARED| replace:: :sql:`ROLLBACK PREPARED` |
|
233 |
.. _ROLLBACK PREPARED: http://www.postgresql.org/docs/9.0/static/sql-rollback-prepared.html |
|
234 |
||
235 |
||
236 |
.. index:: |
|
237 |
pair: Transaction; Recover |
|
238 |
||
239 |
.. method:: tpc_recover() |
|
240 |
||
241 |
Returns a list of `~psycopg2.extensions.Xid` representing pending |
|
242 |
transactions, suitable for use with `tpc_commit()` or |
|
243 |
`tpc_rollback()`. |
|
244 |
||
245 |
If a transaction was not initiated by Psycopg, the returned Xids will |
|
246 |
have attributes `~psycopg2.extensions.Xid.format_id` and |
|
247 |
`~psycopg2.extensions.Xid.bqual` set to `!None` and the |
|
248 |
`~psycopg2.extensions.Xid.gtrid` set to the PostgreSQL transaction ID: such Xids are still |
|
249 |
usable for recovery. Psycopg uses the same algorithm of the |
|
250 |
`PostgreSQL JDBC driver`__ to encode a XA triple in a string, so |
|
251 |
transactions initiated by a program using such driver should be |
|
252 |
unpacked correctly. |
|
253 |
||
254 |
.. __: http://jdbc.postgresql.org/ |
|
255 |
||
256 |
Xids returned by `!tpc_recover()` also have extra attributes |
|
257 |
`~psycopg2.extensions.Xid.prepared`, `~psycopg2.extensions.Xid.owner`, |
|
258 |
`~psycopg2.extensions.Xid.database` populated with the values read |
|
259 |
from the server. |
|
260 |
||
261 |
.. seealso:: the |pg_prepared_xacts|_ system view. |
|
262 |
||
263 |
.. |pg_prepared_xacts| replace:: `pg_prepared_xacts` |
|
264 |
.. _pg_prepared_xacts: http://www.postgresql.org/docs/9.0/static/view-pg-prepared-xacts.html |
|
265 |
||
266 |
||
267 |
||
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
268 |
.. extension:: |
269 |
||
270 |
The above methods are the only ones defined by the |DBAPI| protocol. |
|
271 |
The Psycopg connection objects exports the following additional |
|
272 |
methods and attributes. |
|
273 |
||
274 |
||
275 |
.. attribute:: closed |
|
276 |
||
277 |
Read-only attribute reporting whether the database connection is open |
|
278 |
(0) or closed (1). |
|
279 |
||
280 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
281 |
.. method:: cancel |
282 |
||
283 |
Cancel the current database operation. |
|
284 |
||
285 |
The method interrupts the processing of the current operation. If no |
|
286 |
query is being executed, it does nothing. You can call this function |
|
287 |
from a different thread than the one currently executing a database |
|
288 |
operation, for instance if you want to cancel a long running query if a |
|
289 |
button is pushed in the UI. Interrupting query execution will cause the |
|
290 |
cancelled method to raise a |
|
291 |
`~psycopg2.extensions.QueryCanceledError`. Note that the termination |
|
292 |
of the query is not guaranteed to succeed: see the documentation for |
|
293 |
|PQcancel|_. |
|
294 |
||
295 |
.. |PQcancel| replace:: `!PQcancel()` |
|
296 |
.. _PQcancel: http://www.postgresql.org/docs/8.4/static/libpq-cancel.html#AEN34765 |
|
297 |
||
298 |
.. versionadded:: 2.3 |
|
299 |
||
300 |
||
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
301 |
.. method:: reset |
302 |
||
303 |
Reset the connection to the default. |
|
304 |
||
305 |
The method rolls back an eventual pending transaction and executes the |
|
306 |
PostgreSQL |RESET|_ and |SET SESSION AUTHORIZATION|__ to revert the |
|
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
307 |
session to the default values. A two-phase commit transaction prepared |
308 |
using `~connection.tpc_prepare()` will remain in the database |
|
309 |
available for recover. |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
310 |
|
311 |
.. |RESET| replace:: :sql:`RESET` |
|
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
312 |
.. _RESET: http://www.postgresql.org/docs/9.0/static/sql-reset.html |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
313 |
|
314 |
.. |SET SESSION AUTHORIZATION| replace:: :sql:`SET SESSION AUTHORIZATION` |
|
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
315 |
.. __: http://www.postgresql.org/docs/9.0/static/sql-set-session-authorization.html |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
316 |
|
317 |
.. versionadded:: 2.0.12 |
|
318 |
||
319 |
||
320 |
.. attribute:: dsn |
|
321 |
||
322 |
Read-only string containing the connection string used by the |
|
323 |
connection. |
|
324 |
||
325 |
||
326 |
.. index:: |
|
327 |
pair: Transaction; Autocommit |
|
328 |
pair: Transaction; Isolation level |
|
329 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
330 |
.. method:: set_session([isolation_level,] [readonly,] [deferrable,] [autocommit]) |
331 |
||
332 |
Set one or more parameters for the next transactions or statements in |
|
333 |
the current session. See |SET TRANSACTION|_ for further details. |
|
334 |
||
335 |
.. |SET TRANSACTION| replace:: :sql:`SET TRANSACTION` |
|
336 |
.. _SET TRANSACTION: http://www.postgresql.org/docs/9.1/static/sql-set-transaction.html |
|
337 |
||
338 |
:param isolation_level: set the `isolation level`_ for the next |
|
339 |
transactions/statements. The value can be one of the |
|
340 |
:ref:`constants <isolation-level-constants>` defined in the |
|
341 |
`~psycopg2.extensions` module or one of the literal values |
|
342 |
``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``, |
|
343 |
``SERIALIZABLE``. |
|
344 |
:param readonly: if `!True`, set the connection to read only; |
|
345 |
read/write if `!False`. |
|
346 |
:param deferrable: if `!True`, set the connection to deferrable; |
|
347 |
non deferrable if `!False`. Only available from PostgreSQL 9.1. |
|
348 |
:param autocommit: switch the connection to autocommit mode: not a |
|
349 |
PostgreSQL session setting but an alias for setting the |
|
350 |
`autocommit` attribute. |
|
351 |
||
352 |
The parameters *isolation_level*, *readonly* and *deferrable* also |
|
353 |
accept the string ``DEFAULT`` as a value: the effect is to reset the |
|
354 |
parameter to the server default. |
|
355 |
||
356 |
.. _isolation level: |
|
357 |
http://www.postgresql.org/docs/9.1/static/transaction-iso.html |
|
358 |
||
359 |
The function must be invoked with no transaction in progress. At every |
|
360 |
function invocation, only the specified parameters are changed. |
|
361 |
||
362 |
The default for the values are defined by the server configuration: |
|
363 |
see values for |default_transaction_isolation|__, |
|
364 |
|default_transaction_read_only|__, |default_transaction_deferrable|__. |
|
365 |
||
366 |
.. |default_transaction_isolation| replace:: :sql:`default_transaction_isolation` |
|
367 |
.. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION |
|
368 |
.. |default_transaction_read_only| replace:: :sql:`default_transaction_read_only` |
|
369 |
.. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY |
|
370 |
.. |default_transaction_deferrable| replace:: :sql:`default_transaction_deferrable` |
|
371 |
.. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-DEFERRABLE |
|
372 |
||
373 |
.. note:: |
|
374 |
||
375 |
There is currently no builtin method to read the current value for |
|
376 |
the parameters: use :sql:`SHOW default_transaction_...` to read |
|
377 |
the values from the backend. |
|
378 |
||
379 |
.. versionadded:: 2.4.2 |
|
380 |
||
381 |
||
382 |
.. attribute:: autocommit |
|
383 |
||
384 |
Read/write attribute: if `!True`, no transaction is handled by the |
|
385 |
driver and every statement sent to the backend has immediate effect; |
|
386 |
if `!False` a new transaction is started at the first command |
|
387 |
execution: the methods `commit()` or `rollback()` must be manually |
|
388 |
invoked to terminate the transaction. |
|
389 |
||
390 |
The autocommit mode is useful to execute commands requiring to be run |
|
391 |
outside a transaction, such as :sql:`CREATE DATABASE` or |
|
392 |
:sql:`VACUUM`. |
|
393 |
||
394 |
The default is `!False` (manual commit) as per DBAPI specification. |
|
395 |
||
396 |
.. warning:: |
|
397 |
||
398 |
By default, any query execution, including a simple :sql:`SELECT` |
|
399 |
will start a transaction: for long-running programs, if no further |
|
400 |
action is taken, the session will remain "idle in transaction", a |
|
401 |
condition non desiderable for several reasons (locks are held by |
|
402 |
the session, tables bloat...). For long lived scripts, either |
|
403 |
ensure to terminate a transaction as soon as possible or use an |
|
404 |
autocommit connection. |
|
405 |
||
406 |
.. versionadded:: 2.4.2 |
|
407 |
||
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
408 |
|
409 |
.. attribute:: isolation_level |
|
410 |
.. method:: set_isolation_level(level) |
|
411 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
412 |
.. note:: |
413 |
||
414 |
From version 2.4.2, `set_session()` and `autocommit`, offer |
|
415 |
finer control on the transaction characteristics. |
|
416 |
||
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
417 |
Read or set the `transaction isolation level`_ for the current session. |
418 |
The level defines the different phenomena that can happen in the |
|
419 |
database between concurrent transactions. |
|
420 |
||
421 |
The value set or read is an integer: symbolic constants are defined in |
|
422 |
the module `psycopg2.extensions`: see |
|
423 |
:ref:`isolation-level-constants` for the available values. |
|
424 |
||
425 |
The default level is :sql:`READ COMMITTED`: at this level a |
|
426 |
transaction is automatically started the first time a database command |
|
427 |
is executed. If you want an *autocommit* mode, switch to |
|
428 |
`~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT` before |
|
429 |
executing any command:: |
|
430 |
||
431 |
>>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT) |
|
432 |
||
433 |
See also :ref:`transactions-control`. |
|
434 |
||
435 |
.. index:: |
|
436 |
pair: Client; Encoding |
|
437 |
||
438 |
.. attribute:: encoding |
|
439 |
.. method:: set_client_encoding(enc) |
|
440 |
||
441 |
Read or set the client encoding for the current session. The default |
|
442 |
is the encoding defined by the database. It should be one of the |
|
443 |
`characters set supported by PostgreSQL`__ |
|
444 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
445 |
.. __: http://www.postgresql.org/docs/9.0/static/multibyte.html |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
446 |
|
447 |
||
448 |
.. index:: |
|
449 |
pair: Client; Logging |
|
450 |
||
451 |
.. attribute:: notices |
|
452 |
||
453 |
A list containing all the database messages sent to the client during |
|
454 |
the session. |
|
455 |
||
456 |
.. doctest:: |
|
457 |
:options: NORMALIZE_WHITESPACE |
|
458 |
||
459 |
>>> cur.execute("CREATE TABLE foo (id serial PRIMARY KEY);") |
|
460 |
>>> pprint(conn.notices) |
|
461 |
['NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index "foo_pkey" for table "foo"\n', |
|
462 |
'NOTICE: CREATE TABLE will create implicit sequence "foo_id_seq" for serial column "foo.id"\n'] |
|
463 |
||
464 |
To avoid a leak in case excessive notices are generated, only the last |
|
465 |
50 messages are kept. |
|
466 |
||
467 |
You can configure what messages to receive using `PostgreSQL logging |
|
468 |
configuration parameters`__ such as ``log_statement``, |
|
469 |
``client_min_messages``, ``log_min_duration_statement`` etc. |
|
470 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
471 |
.. __: http://www.postgresql.org/docs/9.0/static/runtime-config-logging.html |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
472 |
|
473 |
||
474 |
.. attribute:: notifies |
|
475 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
476 |
List of `~psycopg2.extensions.Notify` objects containing asynchronous |
477 |
notifications received by the session. |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
478 |
|
479 |
For other details see :ref:`async-notify`. |
|
480 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
481 |
.. versionchanged:: 2.3 |
482 |
Notifications are instances of the `!Notify` object. Previously the |
|
483 |
list was composed by 2 items tuples :samp:`({pid},{channel})` and |
|
484 |
the payload was not accessible. To keep backward compatibility, |
|
485 |
`!Notify` objects can still be accessed as 2 items tuples. |
|
486 |
||
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
487 |
.. index:: |
488 |
pair: Backend; PID |
|
489 |
||
490 |
.. method:: get_backend_pid() |
|
491 |
||
492 |
Returns the process ID (PID) of the backend server process handling |
|
493 |
this connection. |
|
494 |
||
495 |
Note that the PID belongs to a process executing on the database |
|
496 |
server host, not the local host! |
|
497 |
||
498 |
.. seealso:: libpq docs for `PQbackendPID()`__ for details. |
|
499 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
500 |
.. __: http://www.postgresql.org/docs/9.0/static/libpq-status.html#LIBPQ-PQBACKENDPID |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
501 |
|
502 |
.. versionadded:: 2.0.8 |
|
503 |
||
504 |
||
505 |
.. index:: |
|
506 |
pair: Server; Parameters |
|
507 |
||
508 |
.. method:: get_parameter_status(parameter) |
|
509 |
||
510 |
Look up a current parameter setting of the server. |
|
511 |
||
512 |
Potential values for ``parameter`` are: ``server_version``, |
|
513 |
``server_encoding``, ``client_encoding``, ``is_superuser``, |
|
514 |
``session_authorization``, ``DateStyle``, ``TimeZone``, |
|
515 |
``integer_datetimes``, and ``standard_conforming_strings``. |
|
516 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
517 |
If server did not report requested parameter, return `!None`. |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
518 |
|
519 |
.. seealso:: libpq docs for `PQparameterStatus()`__ for details. |
|
520 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
521 |
.. __: http://www.postgresql.org/docs/9.0/static/libpq-status.html#LIBPQ-PQPARAMETERSTATUS |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
522 |
|
523 |
.. versionadded:: 2.0.12 |
|
524 |
||
525 |
||
526 |
.. index:: |
|
527 |
pair: Transaction; Status |
|
528 |
||
529 |
.. method:: get_transaction_status() |
|
530 |
||
531 |
Return the current session transaction status as an integer. Symbolic |
|
532 |
constants for the values are defined in the module |
|
533 |
`psycopg2.extensions`: see :ref:`transaction-status-constants` |
|
534 |
for the available values. |
|
535 |
||
536 |
.. seealso:: libpq docs for `PQtransactionStatus()`__ for details. |
|
537 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
538 |
.. __: http://www.postgresql.org/docs/9.0/static/libpq-status.html#LIBPQ-PQTRANSACTIONSTATUS |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
539 |
|
540 |
||
541 |
.. index:: |
|
542 |
pair: Protocol; Version |
|
543 |
||
544 |
.. attribute:: protocol_version |
|
545 |
||
546 |
A read-only integer representing frontend/backend protocol being used. |
|
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
547 |
Currently Psycopg supports only protocol 3, which allows connection |
548 |
to PostgreSQL server from version 7.4. Psycopg versions previous than |
|
549 |
2.3 support both protocols 2 and 3. |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
550 |
|
551 |
.. seealso:: libpq docs for `PQprotocolVersion()`__ for details. |
|
552 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
553 |
.. __: http://www.postgresql.org/docs/9.0/static/libpq-status.html#LIBPQ-PQPROTOCOLVERSION |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
554 |
|
555 |
.. versionadded:: 2.0.12 |
|
556 |
||
557 |
||
558 |
.. index:: |
|
559 |
pair: Server; Version |
|
560 |
||
561 |
.. attribute:: server_version |
|
562 |
||
563 |
A read-only integer representing the backend version. |
|
564 |
||
565 |
The number is formed by converting the major, minor, and revision |
|
566 |
numbers into two-decimal-digit numbers and appending them together. |
|
567 |
For example, version 8.1.5 will be returned as ``80105``. |
|
568 |
||
569 |
.. seealso:: libpq docs for `PQserverVersion()`__ for details. |
|
570 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
571 |
.. __: http://www.postgresql.org/docs/9.0/static/libpq-status.html#LIBPQ-PQSERVERVERSION |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
572 |
|
573 |
.. versionadded:: 2.0.12 |
|
574 |
||
575 |
||
576 |
.. index:: |
|
577 |
pair: Connection; Status |
|
578 |
||
579 |
.. attribute:: status |
|
580 |
||
581 |
A read-only integer representing the status of the connection. |
|
582 |
Symbolic constants for the values are defined in the module |
|
583 |
`psycopg2.extensions`: see :ref:`connection-status-constants` |
|
584 |
for the available values. |
|
585 |
||
586 |
||
587 |
.. method:: lobject([oid [, mode [, new_oid [, new_file [, lobject_factory]]]]]) |
|
588 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
589 |
Return a new database large object as a `~psycopg2.extensions.lobject` |
590 |
instance. |
|
591 |
||
592 |
See :ref:`large-objects` for an overview. |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
593 |
|
594 |
:param oid: The OID of the object to read or write. 0 to create |
|
595 |
a new large object and and have its OID assigned automatically. |
|
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
596 |
:param mode: Access mode to the object, see below. |
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
597 |
:param new_oid: Create a new object using the specified OID. The |
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
598 |
function raises `~psycopg2.OperationalError` if the OID is already |
599 |
in use. Default is 0, meaning assign a new one automatically. |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
600 |
:param new_file: The name of a file to be imported in the the database |
601 |
(using the |lo_import|_ function) |
|
602 |
:param lobject_factory: Subclass of |
|
603 |
`~psycopg2.extensions.lobject` to be instantiated. |
|
604 |
||
605 |
.. |lo_import| replace:: `!lo_import()` |
|
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
606 |
.. _lo_import: http://www.postgresql.org/docs/9.0/static/lo-interfaces.html#LO-IMPORT |
607 |
||
608 |
Available values for *mode* are: |
|
609 |
||
610 |
======= ========= |
|
611 |
*mode* meaning |
|
612 |
======= ========= |
|
613 |
``r`` Open for read only |
|
614 |
``w`` Open for write only |
|
615 |
``rw`` Open for read/write |
|
616 |
``n`` Don't open the file |
|
617 |
``b`` Don't decode read data (return data as `!str` in Python 2 or `!bytes` in Python 3) |
|
618 |
``t`` Decode read data according to `connection.encoding` (return data as `!unicode` in Python 2 or `!str` in Python 3) |
|
619 |
======= ========= |
|
620 |
||
621 |
``b`` and ``t`` can be specified together with a read/write mode. If |
|
622 |
neither ``b`` nor ``t`` is specified, the default is ``b`` in Python 2 |
|
623 |
and ``t`` in Python 3. |
|
1.1.8
by Fabio Tranchitella
Import upstream version 2.0.14 |
624 |
|
625 |
.. versionadded:: 2.0.8 |
|
1.1.9
by Fabio Tranchitella
Import upstream version 2.2.1 |
626 |
|
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
627 |
.. versionchanged:: 2.4 added ``b`` and ``t`` mode and unicode |
628 |
support. |
|
1.1.9
by Fabio Tranchitella
Import upstream version 2.2.1 |
629 |
|
630 |
||
631 |
.. rubric:: Methods related to asynchronous support. |
|
632 |
||
633 |
.. versionadded:: 2.2.0 |
|
634 |
||
635 |
.. seealso:: :ref:`async-support` and :ref:`green-support`. |
|
636 |
||
637 |
||
638 |
.. attribute:: async |
|
639 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
640 |
Read only attribute: 1 if the connection is asynchronous, 0 otherwise. |
1.1.9
by Fabio Tranchitella
Import upstream version 2.2.1 |
641 |
|
642 |
||
643 |
.. method:: poll() |
|
644 |
||
645 |
Used during an asynchronous connection attempt, or when a cursor is |
|
646 |
executing a query on an asynchronous connection, make communication |
|
647 |
proceed if it wouldn't block. |
|
648 |
||
649 |
Return one of the constants defined in :ref:`poll-constants`. If it |
|
650 |
returns `~psycopg2.extensions.POLL_OK` then the connection has been |
|
651 |
estabilished or the query results are available on the client. |
|
652 |
Otherwise wait until the file descriptor returned by `fileno()` is |
|
653 |
ready to read or to write, as explained in :ref:`async-support`. |
|
654 |
`poll()` should be also used by the function installed by |
|
655 |
`~psycopg2.extensions.set_wait_callback()` as explained in |
|
656 |
:ref:`green-support`. |
|
657 |
||
658 |
`poll()` is also used to receive asynchronous notifications from the |
|
659 |
database: see :ref:`async-notify` from further details. |
|
660 |
||
661 |
||
662 |
.. method:: fileno() |
|
663 |
||
664 |
Return the file descriptor underlying the connection: useful to read |
|
665 |
its status during asynchronous communication. |
|
666 |
||
667 |
||
668 |
.. method:: isexecuting() |
|
669 |
||
1.1.10
by Fabio Tranchitella
Import upstream version 2.4.2 |
670 |
Return `!True` if the connection is executing an asynchronous operation. |
1.1.9
by Fabio Tranchitella
Import upstream version 2.2.1 |
671 |
|
672 |
||
673 |
.. testcode:: |
|
674 |
:hide: |
|
675 |
||
676 |
conn.rollback() |