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
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="generator" content="Docutils: http://docutils.sourceforge.net/">
<link rel="stylesheet" href="default.css" type="text/css" />
<meta name="version" content="#ident "@(#) $Id: README.html,v 1.1 2002/12/05 05:34:30 ballie01 Exp $"" />
</head>
<body>
<div class="document">
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><td class="docinfo-name">Version: </td><td>
#ident "@(#) $Id: README.html,v 1.1 2002/12/05 05:34:30 ballie01 Exp $"</td></tr>
</tbody>
</table>
<div class="section" id="pypgsql-v2-3-python-db-api-2-0-compliant-interface-module-for-postgresql" name="pypgsql-v2-3-python-db-api-2-0-compliant-interface-module-for-postgresql">
<h1>pyPgSQL - v2.3: Python DB-API 2.0 Compliant Interface Module for PostgreSQL.</h1>
<div class="section" id="copyright-notice-and-license" name="copyright-notice-and-license">
<h2>0. Copyright notice and License</h2>
<blockquote>
<p>pyPgSQL, version 2.3
A Python DB-API 2.0 compliant interface for PostgreSQL
Copyright 2000 by Billy G. Allie.
All rights reserved.</p>
<p>Permission to use, copy, modify, and distribute this software and it's
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the copyright owner's name not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.</p>
<p>THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTUOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.</p>
</blockquote>
</div>
<div class="section" id="about-pypgsql" name="about-pypgsql">
<h2>1. About pyPgSQL</h2>
<div class="section" id="introduction" name="introduction">
<h3>1.1 Introduction</h3>
<p>PostgreSQL is a sophisticated Object-Relational DBMS, supporting almost all SQL
constructs, including sub-selects, transactions, and user-defined types and
functions. It is the most advanced open-source database available anywhere More
information about PostgreSQL can be found at the PostgreSQL home page at
<a class="reference" href="http://www.postgresql.org">http://www.postgresql.org</a>.</p>
<p>Python is an interpreted, interactive, object-oriented programming language.
It combines remarkable power with very clear syntax. It has modules, classes,
exceptions, very high level dynamic data types, and dynamic typing. There are
interfaces to many system calls and libraries, as well as to various windowing
systems (X11, Motif, Tk, Mac, MFC). New builtin modules are easily written in
C or C++. Python is also usable as an extension language for applications that
need a programmable interface. Python is copyrighted but freely usable and
distributable, even for commercial use. More information about Python can be
found on the Python home page at <a class="reference" href="http://www.python.org">http://www.python.org</a>.</p>
<p>pyPgSQL is a package of two (2) modules that provide a Python DB-API 2.0
compliant interface to PostgreSQL databases. The first module, libpq,
exports the PostgreSQL C API to Python. This module is written in C and
can be compiled into Python or can be dynamically loaded on demand. The
second module, PgSQL, provides the DB-API 2.0 compliant interface and
support for various PostgreSQL data types, such as INT8, NUMERIC, MONEY,
BOOL, ARRAYS, etc. This module is written in Python. This version works
with PostgreSQL 7.0 or later and Python 2.0 or later.</p>
<p>pyPgSQL was originally developed on a UnixWare 7.1.1 system, but is nowadays
also developed on FreeBSD and various Windows and Linux flavours.</p>
</div>
<div class="section" id="distribution-files" name="distribution-files">
<h3>1.2 Distribution Files</h3>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">README: </td><td class="field-body">This file.</td>
</tr>
<tr class="field"><td class="field-name">Announce: </td><td class="field-body">Announcement of this release.</td>
</tr>
<tr class="field"><td class="field-name">ChangeLog: </td><td class="field-body">changes to this package during it's history.</td>
</tr>
<tr class="field"><td class="field-name">libpqmodule.c: </td><td class="field-body">the C code implementing the libqp module.</td>
</tr>
<tr class="field"><td class="field-name">pgboolean.[ch]: </td><td class="field-body">the C code implementing the PostgreSQL BOOL
type object for Python.</td>
</tr>
<tr class="field"><td class="field-name">pgconnection.[ch]: </td><td class="field-body">the C code implementing the PgConnection
class.</td>
</tr>
<tr class="field"><td class="field-name">pgint2object.[ch]: </td><td class="field-body">the C code implementing the PostgreSQL INT2
type object for Python.</td>
</tr>
<tr class="field"><td class="field-name">pgint8object.[ch]: </td><td class="field-body">the C code implementing the PostgreSQL INT8
type object for Python.</td>
</tr>
<tr class="field"><td class="field-name">pglargeobject.[ch]: </td><td class="field-body">the C code implementing the PgLargeObject
class.</td>
</tr>
<tr class="field"><td class="field-name">pgnotify.[ch]: </td><td class="field-body">the C code implementing the PgNotify class.</td>
</tr>
<tr class="field"><td class="field-name">pgresult.[ch]: </td><td class="field-body">the C code implementing the PgResult class.</td>
</tr>
<tr class="field"><td class="field-name">pgversion.[ch]: </td><td class="field-body">the C code implementing the PgVersion
class.</td>
</tr>
<tr class="field"><td class="field-name">pymemstrdup.c: </td><td class="field-body">the C code implementing a version of strdup()
that uses Python's heap for the needed memory.</td>
</tr>
<tr class="field"><td class="field-name">pyPgSQL/__init__.py: </td><td class="field-body">the initialization code for the pyPgSQL
package.</td>
</tr>
<tr class="field"><td class="field-name">pyPgSQL/PgSQL.py: </td><td class="field-body">the module that implements the Python DB-API 2.0
compliant interface to PostgreSQL</td>
</tr>
<tr class="field"><td class="field-name">pyPgSQL/libpq: </td><td class="field-body">the package for the libpq module.</td>
</tr>
<tr class="field"><td class="field-name">pyPgSQL/libpq/__init__.py: </td><td class="field-body">the initialization code for the libpq
package.</td>
</tr>
<tr class="field"><td class="field-name">setup.py: </td><td class="field-body">Distutil setup file for building and installing
pyPgSQL</td>
</tr>
<tr class="field"><td class="field-name">port/*: </td><td class="field-body">String functions imported from the FreeBSD
source tree and given a pg prefix.</td>
</tr>
<tr class="field"><td class="field-name">test/PgSQLTestCases.py: </td><td class="field-body">A set of functional test cases built using
the Python Unit Testing Framework (PyUnit)</td>
</tr>
<tr class="field"><td class="field-name">test/regression/*: </td><td class="field-body">Test cases to test specific sections of
pyPgSQL.</td>
</tr>
<tr class="field"><td class="field-name">examples/*: </td><td class="field-body">Some example programs using libpq and PgSQL</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="installation" name="installation">
<h3>1.3 Installation</h3>
<p>These instructions assume you have Python 2.0 (or later) and at least
PostgreSQL 7.0 (7.2 or later recommended) installed on your system. If you are
going to use the DB-API 2.0 compliant module, you must also install the
mxDateTime module from <a class="reference" href="http://starship.python.net/~lemburg/mxDateTime.html">http://starship.python.net/~lemburg/mxDateTime.html</a>.</p>
<ol class="loweralpha simple">
<li>Download pyPgSQL files if you haven't already done so.</li>
<li>Edit the setup.py file to reflect the your environment. The setup.py file
contains comments regarding USE_CUSTOM to guide you in customizing this
file.</li>
<li>Execute <tt class="literal">python setup.py build</tt> to build the extension module.</li>
<li>Execute <tt class="literal">python setup.py install</tt> to install the extension module.</li>
</ol>
<p>(On many platforms, you can skip step b. as the necessary paths are
automatically detected.)</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body">You may require root access to install the module.
Consult your local system administrator.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="testing-the-pgsql-module" name="testing-the-pgsql-module">
<h3>1.4 Testing the PgSQL module.</h3>
<p>To run the tests, enter the following command from the PgSQL source
directory:</p>
<blockquote>
<tt class="literal">python test/PgSQLTestCases.py</tt></blockquote>
<p>If the test cases run without any failures, then you can be reasonably sure
that the module built correctly.</p>
<p>There are additional test cases in test/regression that you can run. These
require that an empty database <em>pypgsql</em> exists locally with <em>UNICODE</em>
encoding and with the ability to execute PL/pgsql functions. You can create
such a database with the following commands:</p>
<pre class="literal-block">createdb -E UNICODE pypgsql
createlang plpgsql pypgsql</pre>
</div>
<div class="section" id="additional-information-about" name="additional-information-about">
<h3>1.5 Additional information about ...</h3>
<p>Additional information about the different packages is available at:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">Python: </td><td class="field-body"><a class="reference" href="http://www.python.org">http://www.python.org</a></td>
</tr>
<tr class="field"><td class="field-name">PostgreSQL: </td><td class="field-body"><a class="reference" href="http://www.PostgreSQL.org">http://www.PostgreSQL.org</a></td>
</tr>
<tr class="field"><td class="field-name">mxDateTime: </td><td class="field-body"><a class="reference" href="http://starship.python.net/~lemburg/mxDateTime.html">http://starship.python.net/~lemburg/mxDateTime.html</a></td>
</tr>
</tbody>
</table>
</blockquote>
</div>
</div>
<div class="section" id="programming-information" name="programming-information">
<h2>2. Programming Information</h2>
<div class="section" id="the-libpq-module" name="the-libpq-module">
<h3>2.1 The libpq module</h3>
</div>
<div class="section" id="importing-libpq" name="importing-libpq">
<h3>2.1.1 Importing libpq</h3>
<p>The module, libpq, is part of the pyPgSQL package. It is imported using
the following statement:</p>
<blockquote>
<pre class="doctest-block">>>> from pyPgSQL import libpq</pre>
</blockquote>
</div>
<div class="section" id="libpq-constants" name="libpq-constants">
<h3>2.1.2 libpq Constants</h3>
<p>There are a number of constants defined in libpq. They are intended to be
used as parameters for method calls and to compare against certain results
generated by method calls. You should refer to the libpq section of the
PostgreSQL programmer's manual for information about them. These constants
are:</p>
<blockquote>
<p>Connection related constants:</p>
<blockquote>
CONNECTION_OK, CONNECTION_BAD, POLLING_FAILED, POLLING_READING,
POLLING_WRITING, POLLING_OK, POLLING_ACTIVE</blockquote>
<p>Query related constants:</p>
<blockquote>
EMPTY_QUERY, COMMAND_OK, TUPLES_OK, COPY_OUT, COPY_IN,
BAD_RESPONSE, NONFATAL_ERROR, FATAL_ERROR</blockquote>
<p>Large Object related constants:</p>
<blockquote>
INV_SEEK_SET, INV_SEEK_CUR, INV_SEEK_END, INV_READ, INV_WRITE</blockquote>
<p>Constants for PostgreSQL type (OID) identifiers:</p>
<blockquote>
<p>Character String Types:</p>
<blockquote>
PG_TEXT, PG_CHAR, PG_VARCHAR, PG_NAME, PG_BPCHAR</blockquote>
<p>Number Types:</p>
<blockquote>
PG_INT4, PG_INT2, PG_INT8, PG_OID, PG_NUMERIC, PG_FLOAT8,
PG_FLOAT4, PG_MONEY (aka PG_CASH)</blockquote>
<p>Temporal Types:</p>
<blockquote>
PG_DATE, PG_TIME, PG_TIMESTAMP, PG_TIMESTAMPTX, PG_INTERVAL,
PG_ABSTIME, PG_RELTIME, PG_TINTERVAL</blockquote>
<p>Logical (boolean) Type:</p>
<blockquote>
PG_BOOL</blockquote>
<p>Geometric Types:</p>
<blockquote>
PG_POINT, PG_LSEG, PG_PATH, PG_BOX, PG_LINE, PG_CIRCLE,
PG_POLYGON</blockquote>
<p>Network Types:</p>
<blockquote>
PG_INET, PG_CIDR</blockquote>
<p>Misc. Types:</p>
<blockquote>
PG_REFCURSOR</blockquote>
</blockquote>
</blockquote>
<p>The following constants are defined for use by the libpq module and have no
direct relationship to constants in PostgreSQL's C API:</p>
<blockquote>
<p>PgResult related constants:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">RESULT_DDL: </td><td class="field-body">result was generated by a DDL query.</td>
</tr>
<tr class="field"><td class="field-name">RESULT_DQL: </td><td class="field-body">result was generated by a DQL query.</td>
</tr>
<tr class="field"><td class="field-name">RESULT_DML: </td><td class="field-body">result was generated by a DML query.</td>
</tr>
<tr class="field"><td class="field-name">RESULT_EMPTY: </td><td class="field-body">query generated an empty result.</td>
</tr>
<tr class="field"><td class="field-name">RESULT_ERROR: </td><td class="field-body">query generated an error.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>PgBoolean constants:</p>
<blockquote>
PgTrue, PgFalse</blockquote>
</blockquote>
</div>
<div class="section" id="libpq-methods" name="libpq-methods">
<h3>2.1.3 libpq Methods</h3>
<p>The following methods are defined by libpq:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">PQconnectdb: </td><td class="field-body">preferred method to connect to a database.</td>
</tr>
<tr class="field"><td class="field-name">PQconndefaults: </td><td class="field-body">returns a list containing the connection
defaults.</td>
</tr>
<tr class="field"><td class="field-name">PQresStatus: </td><td class="field-body">returns a string representation of the result
status.</td>
</tr>
<tr class="field"><td class="field-name">PQresType: </td><td class="field-body">returns a string representation of the result
type.</td>
</tr>
<tr class="field"><td class="field-name">PQftypeName: </td><td class="field-body">returns a string name for a PostgreSQL type
(oid).</td>
</tr>
<tr class="field"><td class="field-name">PgBoolean: </td><td class="field-body">creates a PgBoolean object from a string or
number.</td>
</tr>
<tr class="field"><td class="field-name">PgBooleanFromString: </td><td class="field-body">Deprecated, use PgBoolean().</td>
</tr>
<tr class="field"><td class="field-name">PgBooleanFromInteger: </td><td class="field-body">Deprecated, use PgBoolean().</td>
</tr>
<tr class="field"><td class="field-name">PgInt2: </td><td class="field-body">creates a PgInt2 object from a string or
number.</td>
</tr>
<tr class="field"><td class="field-name">PgInt8: </td><td class="field-body">creates a PgInt8 object from a string or
number.</td>
</tr>
<tr class="field"><td class="field-name">PgLargeObject: </td><td class="field-body">creates a PgLargeObject from a connection and
OID.</td>
</tr>
<tr class="field"><td class="field-name">PgVersion: </td><td class="field-body">creates a PgVersion object from a string.</td>
</tr>
<tr class="field"><td class="field-name">PgQuoteString: </td><td class="field-body">Quotes a string, escaping any characters as
needed, for use as input to a character/text
field.</td>
</tr>
<tr class="field"><td class="field-name">PgQuoteBytea: </td><td class="field-body">Escapes a string, which can contain NUL
characters, so that it can used as an input to
a bytea field.</td>
</tr>
<tr class="field"><td class="field-name">PgUnQuoteBytea: </td><td class="field-body">Reverses the action of PgQuoteBytea().</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="pqconnectdb" name="pqconnectdb">
<h3>2.1.3.1 PQconnectdb</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd><p class="first">c = PQconnectdb(conninfo)</p>
<p>Where conninfo is a string containing connection information.</p>
</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgConnection object.</dd>
<dt><em>Description</em>:</dt>
<dd>Implements the PostgreSQL C API's PQconnectdb function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>DatabaseError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="pqconndefaults" name="pqconndefaults">
<h3>2.1.3.2 PQconndefaults</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>l = PQconndefaults()</dd>
<dt><em>Returns</em>:</dt>
<dd>A list of default connection options. A default connection options is
a list containing [keyword, envvar, compiled, val, label, dispchar,
dispsize].</dd>
<dt><em>Description</em>:</dt>
<dd>Implements the PostgreSQL C API's PQconndefaults function.</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="pqresstatus" name="pqresstatus">
<h3>2.1.3.3 PQresStatus</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = PQresStatus(status)</dd>
<dt><em>Returns</em>:</dt>
<dd>A string representation of the result status code, 'status'.</dd>
<dt><em>Description</em>:</dt>
<dd>Implements the PostgreSQL C API's PQresStatus function.</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="pqrestype" name="pqrestype">
<h3>2.1.3.4 PQresType</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = PQresType(type)</dd>
<dt><em>Returns</em>:</dt>
<dd>A string representation of the result type, 'type'.</dd>
<dt><em>Description</em>:</dt>
<dd>The result type is generated by the libpq module (not by the PostgreSQL
C API library) and describes the result type (DDL, DQL, DML, EMPTY, or
ERROR).</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError</dd>
<dt><em>Returns</em>:</dt>
<dd>A string representation of the result type code, 'type'.</dd>
</dl>
</div>
<div class="section" id="pqftypename" name="pqftypename">
<h3>2.1.3.5 PQftypeName</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = PQftypeName(type)</dd>
<dt><em>Returns</em>:</dt>
<dd>A string representation of the PostgreSQL type, 'type'.</dd>
<dt><em>Description</em>:</dt>
<dd>This method returns a string representation of the PostgreSQL type,
'type'. This string is useful for displaying the type code. This
method has no corresponding PostgreSQL C API function.</dd>
</dl>
</div>
<div class="section" id="pgboolean" name="pgboolean">
<h3>2.1.3.6 PgBoolean</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>b = PgBoolean(object)</dd>
<dt><em>Description</em>:</dt>
<dd><p class="first">This method returns a PgBoolean object initialized from the
value of object. It recognizes the following string values:</p>
<blockquote>
For true.: '1', 'T', 'TRUE', 'Y', 'YES', 'ON'
For false: '0', 'F', 'FALSE', 'N', 'NO', 'OFF'</blockquote>
<p>For numeric object, zero is false, non-zero is true.</p>
</dd>
<dt><em>Returns</em>:</dt>
<dd>PgTrue or PgFalse based on the value of 'object'</dd>
</dl>
</div>
<div class="section" id="pgint2" name="pgint2">
<h3>2.1.3.7 PgInt2</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>n = PgInt2(object)</dd>
<dt><em>Description</em>:</dt>
<dd>This method returns a PgInt2 object initialized from the value of the
string or numeric 'object'. The PgInt2 type uses a 2-byte integer to
store it's value.</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgInt2 object initialized with the value of 'object'.</dd>
</dl>
</div>
<div class="section" id="pgint8" name="pgint8">
<h3>2.1.3.8 PgInt8</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>n = PgInt8(object)</dd>
<dt><em>Description</em>:</dt>
<dd>This method returns a PgInt8 object initialized from the value of the
string or numeric 'object'. The PgInt8 type uses a 8-byte integer to
store it's value.</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgInt8 object initialized with the value of 'object'.</dd>
</dl>
</div>
<div class="section" id="pglargeobject" name="pglargeobject">
<h3>2.1.3.9 PgLargeObject</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>o = PgLargeObject(PgConnection, OID)</dd>
<dt><em>Description</em>:</dt>
<dd>This function will create a PgLargeObject object given a PgConnection
object and a PostgreSQL large object identifier (OID).</dd>
<dt><em>Returns</em>:</dt>
<dd>A closed PgLargeObject object.</dd>
<dt><em>Note</em>:</dt>
<dd>A PgLargeObject can not be opened outside the context of a transaction.
Because of this, large objects created with this method (and by
inference, un-pickled large objects) will begin a transaction (if
needed) in it's associated PgConnection object when the the large
object is opened. When the large object is closed, the transaction
will be committed. If a rollback is desired, pass close() an argument
of 1.</dd>
</dl>
</div>
<div class="section" id="pgquotestring" name="pgquotestring">
<h3>2.1.3.10 PgQuoteString</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = PgQuoteString(string, forArray)</dd>
<dt><em>Description</em>:</dt>
<dd><p class="first">This function returns a copy of the input string with the
following characters escaped:</p>
<pre class="literal-block">1. The backslash character (as '\\')
2. The single quote (as "\'")
3. The <CR> character (as '\r')
4. The <NL> character (as '\n')
5. The <BS> character (as '\b')
6. The <FF> character (as '\f')
7. The <TAB> character (as '\t')
8. All other control characters as '\OOO' where OOO is
the octal representation of the character's ordinal
number.
The string is also quoted with single quotes.
If forArray is one (1), the escaping is changed as follows:
1. The backslash character (as '\\\\')
(2 through 7 remain the same)
8. All other control characters as '\\\\000'
9. The double quote (as '\"')
The string is also quoted with double quotes, instead of single
quotes.</pre>
</dd>
<dt><em>Returns</em>:</dt>
<dd>A quoted, escaped copy of the input string.</dd>
</dl>
</div>
<div class="section" id="pgquotebytea" name="pgquotebytea">
<h3>2.1.3.11 PgQuoteBytea</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = PgQuoteBytea(string)</dd>
<dt><em>Description</em>:</dt>
<dd><p class="first">This function returns a copy of the input string with characters
escaped as follows:</p>
<pre class="literal-block">1. <NUL> characters: '\\000' (Note: with 2 backslashes)
2. Non-printable characters: '\OOO' (Note OOO is the octal
representation of the characters ordinal number)
3. Backslashes: '\\\\' (Note: with 4 backslashes)
4. Single quote: "\'"
The string is also quoted with single quotes.
If forArray is one (1), the escaping is changed as follows:
1. <NUL> characters: '\\\\000' (Note: with 4 backslashes)
2. Non-printable characters: '\\\\OOO'
3. Backslashes: '\\\\\\\\' (Note: with 8 backslashes)
4. Single quote: "\'"
5. The double quote (as '\\"')
The string is also quoted with double quotes, instead of single
quotes.</pre>
</dd>
<dt><em>Returns</em>:</dt>
<dd>A quoted, escaped copy of the input string.</dd>
</dl>
</div>
<div class="section" id="pgunquotebytea" name="pgunquotebytea">
<h3>2.1.3.12 PgUnQuoteBytea</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = PgUnQuoteBytea(string)</dd>
<dt><em>Description</em>:</dt>
<dd>This function un-escapes a string retrieved from a bytea field.</dd>
<dt><em>Returns</em>:</dt>
<dd>A copy of the input string with any escaped character returned
to their original value.</dd>
</dl>
</div>
<div class="section" id="libpq-classes" name="libpq-classes">
<h3>2.1.4 libpq Classes</h3>
<p>This module defines the following five (5) classes:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">PgConnection: </td><td class="field-body">the connection class. It handles the connection and all
requests to the database.</td>
</tr>
<tr class="field"><td class="field-name">PgResult: </td><td class="field-body">handles the query results.</td>
</tr>
<tr class="field"><td class="field-name">PgLargeObject: </td><td class="field-body">handles the access to PostgreSQL large objects.</td>
</tr>
<tr class="field"><td class="field-name">PgNotify: </td><td class="field-body">the notify class. It contains information about a
notification event sent from a PostgreSQL backend process.</td>
</tr>
<tr class="field"><td class="field-name">PgVersion: </td><td class="field-body">the version class. It contains information about the
version of the PostgreSQL backend that a connection
object is connected to.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>The module makes error information available via the following exception
objects, in addition to the standard Python exceptions:</p>
<blockquote>
Warning, Error, InterfaceError, DatabaseError, OperationalError,
IntegrityError, InternalError, ProgrammingError, NotSupportedError</blockquote>
<p>Additional information about these exceptions can be found in the Python
DB-API 2.0 documentation.</p>
</div>
<div class="section" id="the-pgconnection-object" name="the-pgconnection-object">
<h3>2.1.4.1 The PgConnection Object</h3>
<p>The PgConnection Object defines a connection to the PostgreSQL database.
It has the following public, read-only attributes:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">host: </td><td class="field-body">The server host name of the connection. It returns the
output of the PQhost PostgreSQL C API function.</td>
</tr>
<tr class="field"><td class="field-name">post: </td><td class="field-body">The port used in the connection. It returns the output of
the PQport function.</td>
</tr>
<tr class="field"><td class="field-name">db: </td><td class="field-body">The database name of the connection. It returns the output
of the PQdb function.</td>
</tr>
<tr class="field"><td class="field-name">options: </td><td class="field-body">The backend options used in the connection. It returns the
output of the PQoptions function.</td>
</tr>
<tr class="field"><td class="field-name">tty: </td><td class="field-body">The debug tty of the connection. It returns the output of
the PQtty function.</td>
</tr>
<tr class="field"><td class="field-name">user: </td><td class="field-body">The user name of the connection. It returns the output of
the PQuser function.</td>
</tr>
<tr class="field"><td class="field-name">status: </td><td class="field-body">The status of the connection. It returns the output of the
PQstatus function.</td>
</tr>
<tr class="field"><td class="field-name">errorMessage: </td><td class="field-body">The error message most recently generated by an operation
on the connection. It returns the output of the
PQerrorMeesage function.</td>
</tr>
<tr class="field"><td class="field-name">backendPID: </td><td class="field-body">The process ID of the backend handling this connection. It
returns the output of the backendPID function.</td>
</tr>
<tr class="field"><td class="field-name">isBusy: </td><td class="field-body">Indicates if PQgetResult would block. Used with
asynchronous query processing. It returns the output of
the PQisBusy function (PostgreSQL 7.0 or later).</td>
</tr>
<tr class="field"><td class="field-name">socket: </td><td class="field-body">The file descriptor for the backend connection socket.
Used with asynchronous query processing. It returns the
output of the PQsocket function.</td>
</tr>
<tr class="field"><td class="field-name">notices: </td><td class="field-body"><p class="first">A list of notices received by the PostgreSQL C API. The
notices are placed in the list so that the list.pop()
method will retrieve the oldest notice on the list.</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body">While this attribute is read-only, you can still
manipulate the list using any of the list's methods
(pop, append, insert, etc.). You just can't assign
a new value to the attribute.</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr class="field"><td class="field-name">version: </td><td class="field-body">version information about the backend that this connection
object is connected to.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>The PgConnection Object has the following methods:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">connectPoll: </td><td class="field-body">Poll the libpq C API for the connection status.</td>
</tr>
<tr class="field"><td class="field-name">query: </td><td class="field-body">Execute a query and wait for the results.</td>
</tr>
<tr class="field"><td class="field-name">sendQuery: </td><td class="field-body">Send a query to the backend without blocking.</td>
</tr>
<tr class="field"><td class="field-name">getResult: </td><td class="field-body">Retrieve the results from the sendQuery method.</td>
</tr>
<tr class="field"><td class="field-name">setnonblocking: </td><td class="field-body">Make the connection non-blocking (or blocking).</td>
</tr>
<tr class="field"><td class="field-name">consumeInput: </td><td class="field-body">If input is available from the backend, consume it.</td>
</tr>
<tr class="field"><td class="field-name">flush: </td><td class="field-body">Attempt to flush any data queued on the backend.</td>
</tr>
<tr class="field"><td class="field-name">requestCancel: </td><td class="field-body">Send a cancel query request to the backend.</td>
</tr>
<tr class="field"><td class="field-name">finish: </td><td class="field-body">Close the connection and free memory used by the PQconn
object.</td>
</tr>
<tr class="field"><td class="field-name">reset: </td><td class="field-body">Reset the communication port with the backend.</td>
</tr>
<tr class="field"><td class="field-name">notifies: </td><td class="field-body">Returns the next notification object (PgNotify) from a list
of unhandled notification objects.</td>
</tr>
<tr class="field"><td class="field-name">getline: </td><td class="field-body">Read a (newline-terminated) line of characters from the
backend.</td>
</tr>
<tr class="field"><td class="field-name">getlineAsync: </td><td class="field-body">Read a line of characters in a non-blocking manner.</td>
</tr>
<tr class="field"><td class="field-name">putline: </td><td class="field-body">Send a null-terminated string to the backend.</td>
</tr>
<tr class="field"><td class="field-name">endcopy: </td><td class="field-body">Sync with the backend (after a Copy-In/Copy-Out operation).</td>
</tr>
<tr class="field"><td class="field-name">lo_creat: </td><td class="field-body">Create a new, empty PgLargeObject.</td>
</tr>
<tr class="field"><td class="field-name">lo_import: </td><td class="field-body">Import a file as a PostgreSQL large object, returning a
PgLargeObject.</td>
</tr>
<tr class="field"><td class="field-name">lo_export: </td><td class="field-body">export a PostgreSQL large object to a file.</td>
</tr>
<tr class="field"><td class="field-name">lo_unlink: </td><td class="field-body">Removes a PostgreSQL large object from the database.</td>
</tr>
<tr class="field"><td class="field-name">trace: </td><td class="field-body">Enable tracing of frontend/backend communications.</td>
</tr>
<tr class="field"><td class="field-name">untrace: </td><td class="field-body">Disable tracing start by the trace method.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="connectpoll-postgresql-7-x-and-above" name="connectpoll-postgresql-7-x-and-above">
<h3>2.1.4.1.1 connectPoll (PostgreSQL 7.x and above)</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>i = c.connectPoll()</dd>
<dt><em>Returns</em>:</dt>
<dd>An integer representing a Postgres Polling Status code.</dd>
<dt><em>Description</em>:</dt>
<dd>This method is used to determine the status of a connection started
with PQconnectStart(). This method implements the PQconnectPoll()
function and is used for asynchronous query processing.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="query" name="query">
<h3>2.1.4.1.2 query</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>r = c.query(string)</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgResult object.</dd>
<dt><em>Description</em>:</dt>
<dd>This method sends the SQL query, 'string', to the backend and
waits for the result. It implement the PostgreSQL C API's
PQexec function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, ProgrammingError, OperationalError,
InternalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="sendquery" name="sendquery">
<h3>2.1.4.1.3 sendQuery</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.sendQuery(string)</dd>
<dt><em>Description</em>:</dt>
<dd>This method send the SQL query, 'string', to the backend without
waiting for the result. It implements the PQsendQuery function and is
used for asynchronous query processing.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InternalError, InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="getresult" name="getresult">
<h3>2.1.4.1.4 getResult</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>r = c.getResult()</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgResult object.</dd>
<dt><em>Description</em>:</dt>
<dd>Wait for and retrieve the results from a previous sendQuery call. It
implements the PQgetResult function and is used for asynchronous query
processing.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, ProgrammingError, OperationalError,
InternalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="setnonblocking-postgresql-7-x-and-above" name="setnonblocking-postgresql-7-x-and-above">
<h3>2.1.4.1.5 setnonblocking (PostgreSQL 7.x and above)</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.setnonblocking(mode)</dd>
<dt><em>Description</em>:</dt>
<dd>Set the connection to non-blocking if 'mode' is non-zero, otherwise set
it to blocking. This method implements the PQsetnonblocking()
function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, InternalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="consumeinput" name="consumeinput">
<h3>2.1.4.1.6 consumeInput</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.consumeInput()</dd>
<dt><em>Description</em>:</dt>
<dd>If input is available from the backend, consume it. This method
implements the PQconsumeInput function and is used with asynchronous
query processing.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, InternalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="flush-postgresql-7-x-and-above" name="flush-postgresql-7-x-and-above">
<h3>2.1.4.1.7 flush (PostgreSQL 7.x and above)</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.flush()</dd>
<dt><em>Description</em>:</dt>
<dd>If input is available from the backend, consume it. This method
implements the PQflush function and is used with asynchronous query
processing.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, InternalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="requestcancel" name="requestcancel">
<h3>2.1.4.1.8 requestCancel</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.requestCancel()</dd>
<dt><em>Description</em>:</dt>
<dd>Send a cancel request to the backend. Note that the successful
dispatching of the request does not mean the request will be canceled.
This method implements the PQrequestCancel function and is used with
asynchronous query processing.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, InternalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="finish" name="finish">
<h3>2.1.4.1.9 finish</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.finish()</dd>
<dt><em>Description</em>:</dt>
<dd>Close the connection to the database and invalidates the PgConnection
object. Any attempt to use the PgConnection object after finish is
called will raise an InterfaceError. Used by the PQconn object. The
database connection is automatically closed when the PgConnection
object is deleted, so calling finish explicitly is never needed. This
method implements and extends the PQfinish function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="reset" name="reset">
<h3>2.1.4.1.10 reset</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.reset()</dd>
<dt><em>Description</em>:</dt>
<dd>Close the connection to the backend and attempt to open a new
connection using the previously used parameters. This method
implements the PQreset function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, DatabaseError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="notifies" name="notifies">
<h3>2.1.4.1.11 notifies</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>n = c.notifies()</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgNotify object containing data for the next notification message, or
None if there are no unhandled notifications.</dd>
<dt><em>Description</em>:</dt>
<dd>Retrieves the next notification from a list of unhandled notification
messages received from the backend. Once a notification object is
returned, it is considered handled and will be removed from the list of
notifications. This method implements the PQnotifies function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="getline" name="getline">
<h3>2.1.4.1.12 getline</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = c.getline()</dd>
<dt><em>Returns</em>:</dt>
<dd>A newline-terminated string read from the backend.</dd>
<dt><em>Description</em>:</dt>
<dd>The getline method reads a newline-terminated string (transmitted by
the backend server) into a (dynamically sized) buffer. This method
implements the PQgetline function and is used with the PostgreSQL COPY
command.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError, MemoryError, InternalError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="getlineasync" name="getlineasync">
<h3>2.1.4.1.13 getlineAsync</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = c.getlineAsync()</dd>
<dt><em>Returns</em>:</dt>
<dd>A newline-terminated string read from the backend in a
non-blocking manner.</dd>
<dt><em>Description</em>:</dt>
<dd>The getlineAsync method reads a newline-terminated string (transmitted
by the backend server) into a (dynamically sized) buffer. This method
implements the PQgetline function and is used with the PostgreSQL COPY
command.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError, MemoryError, InternalError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="putline" name="putline">
<h3>2.1.4.1.14 putline</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.putline(s)</dd>
<dt><em>Returns</em>:</dt>
<dd>Sends a string to the backend.</dd>
<dt><em>Description</em>:</dt>
<dd>The putline method sends a (null-terminated) string to the backend.
This method implements the PQputline function and is used with the
PostgreSQL COPY command.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError, InternalError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="endcopy" name="endcopy">
<h3>2.1.4.1.15 endcopy</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.endcopy()</dd>
<dt><em>Returns</em>:</dt>
<dd>Syncs with the backend.</dd>
<dt><em>Description</em>:</dt>
<dd>This function waits until the backend has finished the copy. It should
either be issued when the last string has been sent to the backend
using putline or when the last string has been received from the
backend using getline. It must be issued or the backend may get "out of
sync" with the frontend. This method implements the PQputline function
and is used with the PostgreSQL COPY command.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError, InternalError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="lo-creat" name="lo-creat">
<h3>2.1.4.1.16 lo_creat</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>lo = c.lo_creat(mode)</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgLargeObject.</dd>
<dt><em>Description</em>:</dt>
<dd>Create a PostgreSQL large object with the given mode. This method
implements the lo_creat function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, OperationalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="lo-import" name="lo-import">
<h3>2.1.4.1.17 lo_import</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>lo = c.lo_import(filename)</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgLargeObject</dd>
<dt><em>Description</em>:</dt>
<dd>Imports a file named 'filename' into a PostgreSQL large object. This
method implements the lo_import function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, OperationalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="lo-export" name="lo-export">
<h3>2.1.4.1.18 lo_export</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.lo_export(oid, filename)</dd>
<dt><em>Returns</em>:</dt>
<dd>A PgLargeObject</dd>
<dt><em>Description</em>:</dt>
<dd>Exports a PostgreSQL large object, represented by oid, to a file named
'filename'. This method implements the lo_import function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, OperationalError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="lo-unlink" name="lo-unlink">
<h3>2.1.4.1.19 lo_unlink</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.lo_unlink(oid)</dd>
<dt><em>Description</em>:</dt>
<dd>Removes the PostgreSQL large object identified by 'oid' from
the database. This method implements the lo_unlink function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, IOError, TypeError</dd>
</dl>
</div>
<div class="section" id="trace" name="trace">
<h3>2.1.4.1.20 trace</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.trace(fileObject)</dd>
<dt><em>Description</em>:</dt>
<dd>Enables tracing of the frontend/backend communications to a
Python File Object, fileObject. This method implements the
PQtrace function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="untrace" name="untrace">
<h3>2.1.4.1.21 untrace</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.untrace()</dd>
<dt><em>Description</em>:</dt>
<dd>Disables tracing enabled by the trace method. This method
implements the lo_import function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="the-pgresult-object" name="the-pgresult-object">
<h3>2.1.4.2 The PgResult Object</h3>
<p>The PgResult object defines the result of a query. It has the following
public, read-only attributes:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">resultType: </td><td class="field-body">the type of the result: DDL, DQL, DML, EMPTY, ERROR.</td>
</tr>
<tr class="field"><td class="field-name">resultStatus: </td><td class="field-body">The result status of the query. It returns the
output of the PQresultStatus PostgreSQL C API
function.</td>
</tr>
<tr class="field"><td class="field-name">ntuples: </td><td class="field-body">The number of tuples (instances) in the query result.
It returns the output of the PQntuples function call.</td>
</tr>
<tr class="field"><td class="field-name">nfields: </td><td class="field-body">The number of fields (attributes) in each tuple of
the query result. It returns the output of the
PQnfields function.</td>
</tr>
<tr class="field"><td class="field-name">binaryTuples: </td><td class="field-body"><p class="first">Contains 1 if the PgResult object contains binary
tuple data, 0 if it contains ASCII data. It returns
the output of the PQbinaryTuples function call.</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body">Binary portals are not supported at this time.</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr class="field"><td class="field-name">cmdStatus: </td><td class="field-body">The command status string from the SQL command that
generated the PGresult. It returns the output to the
PQcmdStatus function.</td>
</tr>
<tr class="field"><td class="field-name">cmdTuples: </td><td class="field-body">The number of rows affected by the SQL command. It
returns the output of the PQcmdTuples function.</td>
</tr>
<tr class="field"><td class="field-name">oidValue: </td><td class="field-body">(7.x and above) The object id of the tuple
inserted, if the SQL command was an INSERT.
Otherwise, contains None. It returns the output of
the PQoidValue function.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>The PgResult Object has the following methods:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">fname: </td><td class="field-body">Returns the field (attribute) name associated with the given
field index.</td>
</tr>
<tr class="field"><td class="field-name">fnumber: </td><td class="field-body">Returns the field (attribute) index associated with the given
field name.</td>
</tr>
<tr class="field"><td class="field-name">ftype: </td><td class="field-body">Returns the type of a field.</td>
</tr>
<tr class="field"><td class="field-name">fsize: </td><td class="field-body">Returns the size in bytes of the field.</td>
</tr>
<tr class="field"><td class="field-name">fmod: </td><td class="field-body">Returns the type-specific modification data of a field.</td>
</tr>
<tr class="field"><td class="field-name">getvalue: </td><td class="field-body">Returns a single field (attribute) value of one tuple of a
PgResult.</td>
</tr>
<tr class="field"><td class="field-name">getlength: </td><td class="field-body">Returns the length of a field (attribute) in bytes.</td>
</tr>
<tr class="field"><td class="field-name">getisnull: </td><td class="field-body">Tests a field for a NULL entry.</td>
</tr>
<tr class="field"><td class="field-name">clear: </td><td class="field-body">Frees the memory used by result.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="fname" name="fname">
<h3>2.1.4.2.1 fname</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>s = r.fname(fidx)</dd>
<dt><em>Returns</em>:</dt>
<dd>The field (attribute) name associate with the given field
index.</dd>
<dt><em>Description</em>:</dt>
<dd>Returns the field (attribute) name associated with the given
field index. Field indices start at 0. It implements the
PQfname PostgreSQL C API function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="fnumber" name="fnumber">
<h3>2.1.4.2.2 fnumber</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>i = r.fnumber(name)</dd>
<dt><em>Returns</em>:</dt>
<dd>The field (attribute) index associated with the given field
name.</dd>
<dt><em>Description</em>:</dt>
<dd>Returns the field (attribute) index associated with the given
field name, 'name'. A -1 is returned if the name does not
match any field. It implements the PQfnumber function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="ftype" name="ftype">
<h3>2.1.4.2.3 ftype</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>i = r.ftype(fidx)</dd>
<dt><em>Returns</em>:</dt>
<dd>Returns the field type associated with the given field index.</dd>
<dt><em>Description</em>:</dt>
<dd>The field type associated with the given field index. The integer
returned is an internal coding of the type. Field indices start at 0.
It implements the PQftype function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="fsize" name="fsize">
<h3>2.1.4.2.4 fsize</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>i = r.fsize(fidx)</dd>
<dt><em>Returns</em>:</dt>
<dd>The size in bytes of the field associated with the given field
index.</dd>
<dt><em>Description</em>:</dt>
<dd>Returns the size in bytes of the field associated with the
given field index. Field indices start at 0. fsize returns
type). -1 is returned if the field is variable size. It
implements the PQfsize function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="fmod" name="fmod">
<h3>2.1.4.2.5 fmod</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>i = r.fmod(fidx)</dd>
<dt><em>Returns</em>:</dt>
<dd>The type-specific modification data of the field associated
with the given field index</dd>
<dt><em>Description</em>:</dt>
<dd>Returns the type-specific modification data of the field associated
with the given field index. Field indices start at 0. It implements
the PQfmod function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="getvalue" name="getvalue">
<h3>2.1.4.2.6 getvalue</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>o = r.getvalue(tidx, fidx)</dd>
<dt><em>Returns</em>:</dt>
<dd>A single field (attribute) value of one tuple of a PGresult.</dd>
<dt><em>Description</em>:</dt>
<dd><p class="first">Returns a single field (attribute) value of one tuple of a
PgResult. Tuple and field indices start at 0. If the field
is NULL, the None is returned. The type of object returned
depends on the PostgreSQL data type of the field:</p>
<blockquote>
<blockquote>
<table frame="border" rules="all">
<colgroup>
<col colwidth="45%" />
<col colwidth="55%" />
</colgroup>
<thead valign="bottom">
<tr><th>PostgreSQL Type</th>
<th>Returned Python Object</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>PG_BOOL</td>
<td>PgBoolean</td>
</tr>
<tr><td>PG_OID</td>
<td>Integer or PgLargeObject(1)</td>
</tr>
<tr><td>PG_INT2</td>
<td>PgInt2</td>
</tr>
<tr><td>PG_INT4</td>
<td>Integer</td>
</tr>
<tr><td>PG_INT8</td>
<td>PgInt8(2) or Long</td>
</tr>
<tr><td>PG_MONEY</td>
<td>Float</td>
</tr>
<tr><td>PG_FLOAT4</td>
<td>Float</td>
</tr>
<tr><td>PG_FLOAT8</td>
<td>Float</td>
</tr>
<tr><td>PG_BYTEA</td>
<td>String(3)</td>
</tr>
<tr><td>All Other Types</td>
<td>String</td>
</tr>
</tbody>
</table>
<ol class="arabic simple">
<li>getvalue() will determine if the OID represents a
PostgreSQL Large Object and returns the appropriate
object.</li>
<li>PgInt8 type is only available on system that have
long long (64 bit integer) support.</li>
<li>Any escaped characters in the string will be returned
to their original value in the returned string.</li>
</ol>
</blockquote>
<p>getvalue implements and extends the PQgetvalue function.</p>
</blockquote>
</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
</dl>
</div>
<div class="section" id="getlength" name="getlength">
<h3>2.1.4.2.7 getlength</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>i = r.getlength(tidx, fidx)</dd>
<dt><em>Returns</em>:</dt>
<dd>The length of a field (attribute) in bytes.</dd>
<dt><em>Description</em>:</dt>
<dd>Returns the length of a field (attribute) in bytes. Tuple and
field indices start at 0. This is the actual data length for
the particular data value, that is the size of the object
pointed to by getvalue. Note that for ASCII-represented values,
this size has little to do with the binary size reported by
fsize. It implements the PQgetlength function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="getisnull" name="getisnull">
<h3>2.1.4.2.8 getisnull</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>i = r.getisnull(tidx, fidx)</dd>
<dt><em>Returns</em>:</dt>
<dd><dl>
<dt>1 if the field contains a NULL, 0 if it contains a non-null</dt>
<dd>value.</dd>
</dl>
</dd>
<dt><em>Description</em>:</dt>
<dd>Tests a field for a NULL entry. Tuple and field indices start
at 0. This function returns 1 if the field contains a NULL, 0
if it contains a non-null value. (Note that getvalue will return None
for a NULL field.) It implements the PQgetisnull function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="clear" name="clear">
<h3>2.1.4.2.9 clear</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>r.clear()</dd>
<dt><em>Description</em>:</dt>
<dd>Frees the storage associated with a PgResult and invalidates
the PgResult object. Any attempt to access the PgResult will
generate an InterfaceError exception. The PgResult is automatically
cleared when the PgResult if deleted, so calling clear explicitly is
never needed. It implements and extends the PQclear function.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, TypeError</dd>
<dt><em>Note</em>:</dt>
<dd>See the PostgreSQL C API documentation for details.</dd>
</dl>
</div>
<div class="section" id="the-pglargeobject-object" name="the-pglargeobject-object">
<h3>2.1.4.3 The PgLargeObject object</h3>
<p>The PgLargeObject class provides methods for accessing the PostgreSQL Large
Object (LO) system. It allows access to the LO using Python's File Object
semantics. The PgLargeObject class defines the following public, read-only
attributes:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">mode: </td><td class="field-body">The mode used to open the LO</td>
</tr>
<tr class="field"><td class="field-name">name: </td><td class="field-body">A string, in the form of "<...>", indicating the source of the LO.</td>
</tr>
<tr class="field"><td class="field-name">closed: </td><td class="field-body">Flag: 1 = the LO is closed.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>and the following public, read-write attribute:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">softspace: </td><td class="field-body">Boolean that indicates whether a space character needs to be
printed before another value when using the 'print' statement.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>The following methods are provided:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">close: </td><td class="field-body">Close the LO. A closed LO can not be read or written anymore.</td>
</tr>
<tr class="field"><td class="field-name">flush: </td><td class="field-body">Flush the internal buffer.</td>
</tr>
<tr class="field"><td class="field-name">open: </td><td class="field-body">Open the LO. A LO can be opened for reading, writing, or both.</td>
</tr>
<tr class="field"><td class="field-name">isatty: </td><td class="field-body">Always returns 0. A LO is never attached to a TTY like device.</td>
</tr>
<tr class="field"><td class="field-name">fileno: </td><td class="field-body">Returns the integer 'file descriptor' used by the underlining
implementation to request I/O operations.</td>
</tr>
<tr class="field"><td class="field-name">read: </td><td class="field-body">Read bytes from the LO.</td>
</tr>
<tr class="field"><td class="field-name">readline: </td><td class="field-body">Read one entire line from the LO.</td>
</tr>
<tr class="field"><td class="field-name">readlines: </td><td class="field-body">Read entire lines from the LO until EOF.</td>
</tr>
<tr class="field"><td class="field-name">seek: </td><td class="field-body">Set the LO's current position, like stdio's fseek().</td>
</tr>
<tr class="field"><td class="field-name">tell: </td><td class="field-body">Returns the LO's current position, like stdio's ftell().</td>
</tr>
<tr class="field"><td class="field-name">write: </td><td class="field-body">Write bytes to the LO.</td>
</tr>
<tr class="field"><td class="field-name">writelines: </td><td class="field-body">Write a list of strings to the LO.</td>
</tr>
<tr class="field"><td class="field-name">export: </td><td class="field-body">Export a LO to a file.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>Since the PgLargeObject follows Python's File Object semantics, refer to the
documentation for File Objects for details on using PgLargeObject. There are
a few differences, which will be detailed here.</p>
</div>
<div class="section" id="open" name="open">
<h3>2.1.4.3.1 open</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>lo.open(mode)</dd>
<dt><em>Description</em>:</dt>
<dd><p class="first">Opens a PostgreSQL Large Object for reading, writing, or both.
The 'mode' parameter can be either an integer consisting of a
combination of the INV_READ and INV_WRITE mode bits, or a
string containing 'r' for reading, or 'w' for writing. The LO
can be open for updating by using 'r+' or 'w+'. A 'b' can be
included in the mode string to indicate opening the LO for binary data,
but is not really needed since PostgreSQL does not differentiate
between binary and non-binary data.</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body">'w+' will NOT truncate the large object.</td>
</tr>
</tbody>
</table>
</dd>
<dt><em>Note</em>:</dt>
<dd>Open is a built-in function of Python, not a method of the File
Object. If there is not transaction started on the associated
PgConnection object when open is called, one is started. This
will only occur for un-pickled large objects and large objects
created with the PgLargeObject method of libpq (and PgSQL).</dd>
</dl>
</div>
<div class="section" id="close" name="close">
<h3>2.1.4.3.2 close</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>lo.close()</dd>
<dt><em>Description</em>:</dt>
<dd>This method will close an open large object.</dd>
<dt><em>Note</em>:</dt>
<dd>If the large object was the result of un-pickling a large
object or it was created with the PgLargeObject method of
libpq (or PgSQL), close() will commit the transaction started
by open(). If a rollback is desired, then pass close a single
argument of the integer 1. This argument is only valid if the
large object was the result of un-pickling a large object or
created with the PgLargeObject method.</dd>
</dl>
</div>
<div class="section" id="export" name="export">
<h3>2.1.4.3.3 export</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>i = lo.export(filename)</dd>
<dt><em>Returns</em>:</dt>
<dd>1 if successful, 0 if an OS error occurred, < 0 if a database
error occurred.</dd>
<dt><em>Description</em>:</dt>
<dd>This method will export the PostgreSQL large object to the
specified UNIX filename.</dd>
<dt><em>Note</em>:</dt>
<dd>The file is stored on the database server, not the client machine (if
different from the server).</dd>
</dl>
</div>
<div class="section" id="the-pgnotify-object" name="the-pgnotify-object">
<h3>2.1.4.4 The PgNotify Object</h3>
<p>The PgNotify object encapsulates the data returned by the notifies method of
the PgConnection class. It provides the following read-only attributes:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">relname: </td><td class="field-body">The name of the relation containing data.</td>
</tr>
<tr class="field"><td class="field-name">be_pid: </td><td class="field-body">The process ID of the PostgreSQL backend sending the
notification.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="the-pgversion-object" name="the-pgversion-object">
<h3>2.1.4.5 The PgVersion Object</h3>
<p>The PgVersion object encapsulates information about the version of PostgreSQL
that a connection object is connected to. It provides the following read-only
attribute:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">major: </td><td class="field-body">The major version number.</td>
</tr>
<tr class="field"><td class="field-name">minor: </td><td class="field-body">The minor version number.</td>
</tr>
<tr class="field"><td class="field-name">level: </td><td class="field-body">The patch level.</td>
</tr>
<tr class="field"><td class="field-name">post70: </td><td class="field-body">A flag that is true if the version is >= 7.1.0.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>You can obtain the result of the 'SELECT version()' used to initialize this
object using the str() or repr() function.</p>
<p>For example, for version 6.5.3, the contents of the PgVersion object would be:</p>
<blockquote>
<pre class="literal-block">connection.version == "PostgreSQL 6.5.3 on <system dependent info>"
connection.version.major == 6
connection.version.minor == 5
connection.version.level == 3
connection.version.post70 == 0</pre>
</blockquote>
<p>For example, for version 7.1.1, the contents of PgVer would be:</p>
<blockquote>
<pre class="literal-block">connection.version == "PostgreSQL 7.1.1 on <system dependent info>"
connection.version.major == 7
connection.version.minor == 1
connection.version.level == 1
connection.version.post70 == 1</pre>
</blockquote>
<p>Also, you can use the PgVersion object to compare against a number or string
form of the version. The form used for numeric comparison is "Mmmll", where
"M" is the major number, "mm" is the minor number, and "ll" is the patch level.
An example:</p>
<blockquote>
<p>Assume that the PostgreSQL version is 7.0.2, then:</p>
<blockquote>
<pre class="literal-block">connection.version == 70002 will be true.
connection.version < 70001L will be false.
connection.version > 70001.0 will be true.</pre>
</blockquote>
</blockquote>
<p>You can also compare against a string as follows:</p>
<blockquote>
<p>Assume that the PostgreSQL version is 7.1.2, then:</p>
<blockquote>
<pre class="literal-block">connection.version == "7.0.2" will be false.
connection.version < "7.0.1" will be false.
connection.version > "7.1" will be true.</pre>
</blockquote>
</blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body">Both the libpq and PgSQL connection objects have the version attribute.</td>
</tr>
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body">Comparisons against strings (i.e. "7.0.1") does not work in
Python 2.0.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="the-pgsql-module" name="the-pgsql-module">
<h3>2.2 The PgSQL module</h3>
<p>The PgSQL module provide a Python DB-API 2.0 compliant module on top of the
libpq module. As the DB-API 2.0 interface is documented elsewhere
(<a class="reference" href="http://www.python.org/topics/database/DatabaseAPI-2.0.html">http://www.python.org/topics/database/DatabaseAPI-2.0.html</a>), I will only
describe the differences in the PgSQL here.</p>
</div>
<div class="section" id="importing-pgsql" name="importing-pgsql">
<h3>2.2.1 Importing PgSQL</h3>
<p>The module, PgSQL, is part of the pyPgSQL package. It is imported using
the following statement:</p>
<blockquote>
<pre class="doctest-block">>>> from pyPgSQL import PgSQL</pre>
</blockquote>
</div>
<div class="section" id="differences-at-the-module-level" name="differences-at-the-module-level">
<h3>2.2.2 Differences at the Module Level</h3>
<ol class="arabic">
<li><p class="first">The Binary constructor is a method of the Connection object, not the module.
For PostgreSQL, a Large Object can only be created in conjunction with a
Connection, it has no meaning outside of the context of a Connection.</p>
</li>
<li><p class="first">The following types are defined to support certain PostgreSQL data types:</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">PgInt2: </td><td class="field-body"><p class="first">Supports the PG_INT2 data type.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgInt8: </td><td class="field-body"><p class="first">Supports the PG_INT8 data type.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgBoolean: </td><td class="field-body"><p class="first">Supports the PG_BOOL data type.</p>
</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">The following classes are defined to support certain PostgreSQL data types:</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">PgNumeric: </td><td class="field-body"><p class="first">Supports the PG_NUMERIC data type. It uses a Python Long as
the base type and provides the following arithmetic operations:
addition, subtraction, multiplication, and division.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgMoney: </td><td class="field-body"><p class="first">Supports the PG_CASH data type. It uses a Python Float as the
base type with range checking to prevent it from exceeding the
range of the PG_CASH data type. Any operation that applies to
a Python Float can be used with a PgMoney object.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgBytea: </td><td class="field-body"><p class="first">This class supports the PG_BYTEA data type. It is a wrapper
around a Python String that provides for proper escaping of
the string when used in a query.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgOther: </td><td class="field-body"><p class="first">This class supports all the other PostgreSQL data types that
do not map directly into a Python object or one of the support
classes listed above (such as PG_BOX, PG_POINT, etc.). As time
goes on, more PostgreSQL data types will have support classes
defined for them, reducing the number of PostgreSQL data types
that fall within this class.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgArray: </td><td class="field-body"><p class="first">This class provide support for PostgreSQL arrays. It is a
wrapper around a Python list that supports all the methods of
a list plus adds a __quote__ method for quoting arrays.</p>
</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">The following class is defined:</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">PgVersion: </td><td class="field-body"><p class="first">Contains the version number of PostgreSQL database engine that
we are connected to. This information is used to change the
behavior of PgSQL based on the version of the PostgreSQL
engine. See the section 2.6 for more details on the
PgVersion object.</p>
</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">The following constructors are defined by the PgSQL module.</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">PgBoolean: </td><td class="field-body"><p class="first">Construct a PgBoolean from a Python numeric or string.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgInt2: </td><td class="field-body"><p class="first">Construct a PgInt2 from a Python numeric or string.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgInt8: </td><td class="field-body"><p class="first">Construct a PgInt8 from a Python numeric or string.</p>
</td>
</tr>
<tr class="field"><td class="field-name">PgLargeObject: </td><td class="field-body"><p class="first">Construct a PgLargeObject from a PgConnection object and
a OID identifying a PostgreSQL large object.</p>
</td>
</tr>
</tbody>
</table>
<p>These constructors are documented in the libpq section of this document.</p>
</li>
<li><p class="first">The following attribute is defined in the PgSQL module:</p>
<blockquote>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">fetchReturnsList: </td><td class="field-body"><p class="first">controls the type of result returns by the fetchXXX
methods.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
<p>Setting this attribute to 1 will cause the fetchXXX methods to return a
list instead of a PgResultSet. This will provide better performance by
sacrificing the convenient access methods provide by a PgResultSet.</p>
<p>The default value for fetchReturnsList is 0.</p>
</li>
</ol>
</div>
<div class="section" id="differences-in-the-connection-object" name="differences-in-the-connection-object">
<h3>2.2.3 Differences in the Connection Object</h3>
<ol class="arabic">
<li><p class="first">The Connection object has an additional read-only attribute called notices.
This attribute is a list of notices returned by the pq library.</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body"><p class="first">Under normal usage, certain (but not all) notices received from
the libpq C-API library are converted into Warning exceptions.</p>
</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">The Connection object has an additional read-only attribute called version.
This attribute contains a PgVersion object encapsulating the version
information of the PostgreSQL backend that the Connection object is
connected to.</p>
</li>
<li><p class="first">The Binary constructor method is a Connection method, not a PgSQL module
function.</p>
</li>
<li><p class="first">A unlink method is available in the Connection object to remove a Large
Object from the database.</p>
</li>
<li><p class="first">A PgSQL specific Connection attribute, called TransactionLevel, specifies
the isolation level to use within a transaction. It can be set to "",
"READ COMMITED", or "SERIALIZABLE". PgSQL will issue the appropriate "SET
TRANSACTION LEVEL" statement whenever a new transaction is started for
the connection.</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body"><p class="first">The value of this attribute can not be changed if there are any
active cursors for the connection.</p>
</td>
</tr>
</tbody>
</table>
</li>
</ol>
</div>
<div class="section" id="unlink" name="unlink">
<h3>2.2.3.1 unlink</h3>
<dl>
<dt><em>Syntax</em>:</dt>
<dd>c.unlink(PgLargeObject)</dd>
<dt><em>Description</em>:</dt>
<dd>Removes the PostgreSQL large object identified from the
database.</dd>
<dt><em>Exceptions</em>:</dt>
<dd>InterfaceError, IOError, TypeError</dd>
</dl>
</div>
<div class="section" id="differences-in-the-cursor-object" name="differences-in-the-cursor-object">
<h3>2.2.4 Differences in the Cursor Object</h3>
<ol class="arabic">
<li><p class="first">The description attribute is a sequence of 8-item sequences. The first
seven items are the same as described in the DB-API 2.0 documentation.
The 8th item is the 'isArray' flag. If this is 1, then the associated
result column is a PostgreSQL array.</p>
</li>
<li><p class="first">The callproc method will always return None. PostgreSQL does not have
stored procedures in the same sense as other databases such as Oracle.
There are no 'Input', 'Output', or 'Input/Output' parameters. In PgSQL,
this method is used to call PostgreSQL functions, which only return a
result set (or nothing).</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body"><p class="first">Beginning with PostgreSQL 7.2, it is possible to return a
reference to a cursor from PL/pgSQL. PgSQL will create a new
Cursor object for the referenced cursor that is returned.</p>
</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">When using the execute method, you should only use '%s' [or '%(name)s']
(without the quote marks) to specify locations where the parameters are to
be substituted, even for integers, floats and other non-string variables.
The execute method will convert all the parameters to a string, applying any
quoting that may be necessary before sending the query to the back-end.</p>
</li>
<li><p class="first">The fetchone method will return a PgResultSet object instead of a sequence.
A PgResultSet emulates a Python List object (for DB-API 2.0 compliance),
but also acts as a dictionary and allows the column data to be retrieved by
using the column name as an attribute of the PgResultSet object. The column
names are case-insensitive.</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body"><p class="first">This feature is controlled by the fetchReturnsList attribute of
the PgSQL module.</p>
</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">The fetchmany and fetchall methods return a sequence of PgResultSet objects
instead of a sequence of sequences.</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><td class="field-name">NOTE: </td><td class="field-body"><p class="first">This feature is controlled by the fetchReturnsList attribute of
the PgSQL module.</p>
</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">A PostgreSQL specific attribute, named oidValue, was added to the cursor
object. This attribute returns the value of the oidValue attribute of the
PgResult object associated with the cursor object and provides a convenient
way to get the object ID of a newly inserted record.</p>
</li>
</ol>
</div>
</div>
<div class="section" id="general-notes-and-observations" name="general-notes-and-observations">
<h2>3.0 General Notes and Observations</h2>
<p>The PostgreSQL database system has no auto-commit setting. It is always in
auto-commit mode unless a transaction is started. To achieve the DB-API 2.0
mandated behaviour, when connection.autocommit is 0, a transaction is
started when the first cursor is created for a connection. After a commit
or rollback, a new transaction is created on the next call to execute().</p>
<hr />
<p>PostgreSQL arrays are no longer (directly) represented by Python lists.
This means that lists and tuples are not longer treated specially by
Cursor.execute(). This resolves a problem of using the IN SQL syntax with
Cursor.execute(). For example, the following statement will now work:</p>
<blockquote>
<pre class="doctest-block">>>> Cursor.execute('select * from table where column1 in %s', ((1, 3, 4),))</pre>
</blockquote>
<p>It will generate the following SQL statement:</p>
<blockquote>
select * from table where column1 in (1, 3, 4)</blockquote>
<p>It also means that to insert an PostgreSQL array, you must pass a PgArray
instance to Cursor.execute(). For example, if you have a list that you want
to insert into a table as a PostgreSQL array, you would use:</p>
<blockquote>
<pre class="doctest-block">>>> cursor.execute('insert in sometable values (%s)', PgArray(yourlist))</pre>
</blockquote>
<p>You can also build a PostgreSQL array by creating an empty PgArray instance
and populating it using the various list methods (.append(), .insert(), etc.).</p>
<hr />
<p>When working with PostgreSQL large object, you MUST be in a transaction.
The code will try to ensure that a transaction is active while working with
large object (i.e. lo_open will start a transaction if necessary. lo_close
will end the transaction if it determines that lo_open started one.)</p>
<hr />
<p>Beginning with PostgreSQL 7.2, you can now create a cursor in PL/pgSQL and
return a reference to that cursor. PgSQL will transform the reference to
the created cursor into a Cursor object that can be used to fetch the
results of the cursor. For example (assuming that mmYearInfo returns a
reference cursor):</p>
<blockquote>
<pre class="doctest-block">>>> from pyPgSQL import PgSQL
>>> cx = PgSQL.connect(database='esi')
>>> cu = cx.cursor()
>>> cu.callproc('mmYearInfo')
>>> rs = cu.fetchone()
>>> rs
[<pyPgSQL.PgSQL.Cursor instance at 0x818495c>]
>>> c = rs[0]
>>> for i in c.description:
... print i
...
['model_year', varchar, 4, 8, None, None, None, 0]
['mktg_div_name', varchar, 50, 54, None, None, None, 0]
['model_desc', varchar, 50, 54, None, None, None, 0]
['book_types', varchar, 50, 54, None, None, None, 0]
['vehicle_syskey', integer, 4, 4, None, None, None, 0]
>>> r = c.fetchone()
>>> r
['2003', 'Buick', 'Century', '1;8;9', 2211]
>>> </pre>
</blockquote>
</div>
</div>
</div>
</body>
</html>
|
