1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
.. currentmodule:: psycopg
Other top-level objects
=======================
Connection information
----------------------
.. autoclass:: ConnectionInfo()
The object is usually returned by `Connection.info`.
.. autoattribute:: dsn
.. note:: The `get_parameters()` method returns the same information
as a dict.
.. autoattribute:: status
The status can be one of a number of values. However, only two of
these are seen outside of an asynchronous connection procedure:
`~pq.ConnStatus.OK` and `~pq.ConnStatus.BAD`. A good connection to the
database has the status `!OK`. Ordinarily, an `!OK` status will remain
so until `Connection.close()`, but a communications failure might
result in the status changing to `!BAD` prematurely.
.. autoattribute:: transaction_status
The status can be `~pq.TransactionStatus.IDLE` (currently idle),
`~pq.TransactionStatus.ACTIVE` (a command is in progress),
`~pq.TransactionStatus.INTRANS` (idle, in a valid transaction block),
or `~pq.TransactionStatus.INERROR` (idle, in a failed transaction
block). `~pq.TransactionStatus.UNKNOWN` is reported if the connection
is bad. `!ACTIVE` is reported only when a query has been sent to the
server and not yet completed.
.. autoattribute:: pipeline_status
.. autoattribute:: backend_pid
.. autoattribute:: vendor
Normally it is `PostgreSQL`; it may be different if connected to
a different database.
.. versionadded:: 3.1
.. autoattribute:: server_version
The number is formed by converting the major, minor, and revision
numbers into two-decimal-digit numbers and appending them together.
Starting from PostgreSQL 10 the minor version was dropped, so the
second group of digits is always 00. For example, version 9.3.5 is
returned as 90305, version 10.2 as 100002.
.. autoattribute:: error_message
.. automethod:: get_parameters
.. note:: The `dsn` attribute returns the same information in the form
as a string.
.. autoattribute:: timezone
.. code:: pycon
>>> conn.info.timezone
zoneinfo.ZoneInfo(key='Europe/Rome')
.. autoattribute:: host
This can be a host name, an IP address, or a directory path if the
connection is via Unix socket. (The path case can be distinguished
because it will always be an absolute path, beginning with ``/``.)
.. autoattribute:: hostaddr
Only available if the libpq used is at least from PostgreSQL 12.
Raise `~psycopg.NotSupportedError` otherwise.
.. autoattribute:: port
.. autoattribute:: dbname
.. autoattribute:: user
.. autoattribute:: password
.. autoattribute:: options
.. automethod:: parameter_status
Example of parameters are ``server_version``,
``standard_conforming_strings``... See :pq:`PQparameterStatus()` for
all the available parameters.
.. autoattribute:: encoding
The value returned is always normalized to the Python codec
`~codecs.CodecInfo.name`::
conn.execute("SET client_encoding TO LATIN9")
conn.info.encoding
'iso8859-15'
A few PostgreSQL encodings are not available in Python and cannot be
selected (currently ``EUC_TW``, ``MULE_INTERNAL``). The PostgreSQL
``SQL_ASCII`` encoding has the special meaning of "no encoding": see
:ref:`adapt-string` for details.
.. seealso::
The `PostgreSQL supported encodings`__.
.. __: https://www.postgresql.org/docs/current/multibyte.html
The description `Column` object
-------------------------------
.. autoclass:: Column()
An object describing a column of data from a database result, `as described
by the DBAPI`__, so it can also be unpacked as a 7-items tuple.
The object is returned by `Cursor.description`.
.. __: https://www.python.org/dev/peps/pep-0249/#description
.. autoattribute:: name
.. autoattribute:: type_code
.. autoattribute:: display_size
.. autoattribute:: internal_size
.. autoattribute:: precision
.. autoattribute:: scale
Notifications
-------------
.. autoclass:: Notify()
The object is usually returned by `Connection.notifies()`.
.. attribute:: channel
:type: str
The name of the channel on which the notification was received.
.. attribute:: payload
:type: str
The message attached to the notification.
.. attribute:: pid
:type: int
The PID of the backend process which sent the notification.
Pipeline-related objects
------------------------
See :ref:`pipeline-mode` for details.
.. autoclass:: Pipeline
This objects is returned by `Connection.pipeline()`.
.. automethod:: sync
.. automethod:: is_supported
.. autoclass:: AsyncPipeline
This objects is returned by `AsyncConnection.pipeline()`.
.. automethod:: sync
Transaction-related objects
---------------------------
See :ref:`transactions` for details about these objects.
.. autoclass:: IsolationLevel
:members:
The value is usually used with the `Connection.isolation_level` property.
Check the PostgreSQL documentation for a description of the effects of the
different `levels of transaction isolation`__.
.. __: https://www.postgresql.org/docs/current/transaction-iso.html
.. autoclass:: Transaction()
.. autoattribute:: savepoint_name
.. autoattribute:: connection
.. autoclass:: AsyncTransaction()
.. autoattribute:: connection
.. autoexception:: Rollback
It can be used as:
- ``raise Rollback``: roll back the operation that happened in the current
transaction block and continue the program after the block.
- ``raise Rollback()``: same effect as above
- :samp:`raise Rollback({tx})`: roll back any operation that happened in
the `Transaction` `!tx` (returned by a statement such as :samp:`with
conn.transaction() as {tx}:` and all the blocks nested within. The
program will continue after the `!tx` block.
Two-Phase Commit related objects
--------------------------------
.. autoclass:: Xid()
See :ref:`two-phase-commit` for details.
.. autoattribute:: format_id
Format Identifier of the two-phase transaction.
.. autoattribute:: gtrid
Global Transaction Identifier of the two-phase transaction.
If the Xid doesn't follow the XA standard, it will be the PostgreSQL
ID of the transaction (in which case `format_id` and `bqual` will be
`!None`).
.. autoattribute:: bqual
Branch Qualifier of the two-phase transaction.
.. autoattribute:: prepared
Timestamp at which the transaction was prepared for commit.
Only available on transactions recovered by `~Connection.tpc_recover()`.
.. autoattribute:: owner
Named of the user that executed the transaction.
Only available on recovered transactions.
.. autoattribute:: database
Named of the database in which the transaction was executed.
Only available on recovered transactions.
|
