« back to all changes in this revision
Viewing changes to README
- browse files at revision 2
- compare with another revision
- download diff
- download tarball
- view history from revision 2
- Committer: Federico Di Gregorio
- Date: 2004-10-29 16:08:31 UTC
- Revision ID: fog-3d8587a243fa1d89012217ea99d2486813eb1955
SVN repo up to date (1.1.16pre1).
added
removed
README
1
1
psycopg - Python-PostgreSQL Database Adapter
2
2
********************************************
3
3
4
psycopg is a PostgreSQL database adapter for the Python programming
5
language. This is version 2, a complete rewrite of the original code to
6
provide new-style classes for connection and cursor objects and other sweet
7
candies. Like the original, psycopg 2 was written with the aim of being
8
very small and fast, and stable as a rock.
9
10
psycopg is different from the other database adapter because it was
11
designed for heavily multi-threaded applications that create and destroy
12
lots of cursors and make a conspicuous number of concurrent INSERTs or
13
UPDATEs. psycopg 2 also provide full asycronous operations for the really
14
brave programmer.
15
16
There are confirmed reports of psycopg 1.x compiling and running on Linux
17
and FreeBSD on i386, Solaris, MacOS X and win32 architectures. psycopg 2
18
does not introduce build-wise incompatible changes so it should be able to
19
compile on all architectures just as its predecessor did.
20
21
Now go read the INSTALL file. More information about psycopg extensions to
22
the DBAPI-2.0 is available in the files located in the doc/ direcory.
23
4
psycopg is a PostgreSQL database adapter for the Python programming language
5
(just like pygresql and popy.) It was written from scratch with the aim of
6
being very small and fast, and stable as a rock. The main advantages of
7
psycopg are that it supports (well... *will* support) the full Python
8
DBAPI-2.0 and being thread safe at level 2.
9
10
psycopg is different from the other database adapter because it was designed
11
for heavily multi-threaded applications that create and destroy lots of
12
cursors and make a conspicuous number of concurrent INSERTs or UPDATEs.
13
Every open Python connection keeps a pool of real (UNIX or TCP/IP) connections
14
to the database. Every time a new cursor is created, a new connection does not
15
need to be opened; instead one of the unused connections from the pool is
16
used. That makes psycopg very fast in typical client-server applications that
17
create a servicing thread every time a client request arrives.
18
19
psycopg now support the Python DBAPI-2.0 completely. There are confirmed
20
reports of psycopg compiling and running on Linux and FreeBSD on i386, Solaris
21
and MacOS X.
22
23
24
Extensions to the Python DBAPI-2.0
25
----------------------------------
26
27
psycopg offers some little extensions on the Python DBAPI-2.0. Note that the
28
extension do not make psycopg incompatible and you can still use it without
29
ever knowing the extensions are here.
30
31
The DBAPI-2.0 mandates that cursors derived from the same connection are not
32
isolated, i.e., changes done to the database by one of them should be
33
immediately visible by all the others. This is done by serializing the queries
34
on the same physical connection to the database (PGconn struct in C.)
35
Serializing queries when the network latencies are hight (and network speed is
36
low) dramatically lowers performance, so it is possible to put a connection
37
into not-serialized mode, by calling the .serialize() method giving it a
38
0-value argument or by creating a connection using the following code:
39
40
conn = psycopg.connect("dbname=...", serialize=0)
41
42
After that every cursor will get its own physical connection to the database
43
and multiple threads will go at full speed. Note that this feature makes the
44
new cursors non-compliant respect to the DBAPI-2.0.
45
46
The main extension is that we support (on not-serialized cursors) per-cursor
47
commits. If you do a commit() on the connection all the changes on all the
48
cursors derived from that connection are committed to the database (in random
49
order, so take your care.) But you can also call commit() on a single cursor
50
to commit just the operations done on that cursor. Pretty nice.
51
52
Note that you *do have* to call .commit() on the cursors or on the connection
53
if you want to change your database. Note also that you *do have* to call
54
commit() on a cursor even before a SELECT if you want to see the changes
55
apported by other threads to the database.
56
57
Also note that you *can't* (I repeat: *you* *can't*) call .commit() on cursor
58
derived from a serialized connection: trying that will give you an exception
59
with the message: "serialized connection: cannot commit on this cursor". If
60
you want to use the per-cursor commit feature you need to create a
61
non-serialized connection, as explained above.
62
63
From version 0.4.1 psycopg supports autocommit mode. You can set the default
64
mode for new cursor by setting the 'autocommit' variable to 0 or 1 on the
65
connection before creating a new cursor with the cursor() method. On an
66
already created cursor you can change the commit mode by calling the
67
autocommit() method. Giving no arguments or 1 switches autocommit on, 0
68
switches it off.
69
70
Obviously everything said about commit is valid for rollbacks too.
71
72
73
The type system
74
---------------
75
76
The DBAPI-2.0 specify that should be possible to check for the column type
77
reported in the second field of the description tuple of the cursor used for a
78
SELECT using 'singletons' like NUMBER, STRING, etc. While this is fully
79
supported by psycopg from release 0.3 on, we went forward and implemented
80
support for custom typecasting from PostgreSQL to Python types using
81
user-defined functions. See the examples test/check_types.py and
82
doc/examples/usercast.py for more information. In particular usercast_test.py
83
shows how to implement a callback that translates the PostgreSQL box type to
84
an ad-hoc Python class with instances created automagically on SELECT.
85
86
87
Compile-time configuration options
88
----------------------------------
89
90
To build psycopg you will need a C compiler (gcc), the Python development
91
files (headers and libraries), the PostgreSQL header and libraries and the
92
mxDateTime header files (and the mxDateTime Python package installed, version
93
>= 2.0.0, of curse.)
94
95
The following options are specific to psycopg and can be set when running
96
configure before issuing 'make' to compile the package.
97
98
--with-postgres-libraries=DIR
99
PostgreSQL 7.x libraries (libpq.so) are in directory DIR
100
101
--with-postgres-includes=DIR
102
PostgreSQL 7.x header files are located in directory DIR
103
104
--with-mxdatetime-includes=DIR
105
MXDateTime Python extension header files are located in directory DIR
106
107
--with-zope=DIR
108
install the ZPsycopgDA Zope Product into DIR (use 'make install-zope')
109
110
--enable-devel[=yes/no]
111
Enable developer features like debugging output and extra assertions.
112
113
Some random notes about python versions and paths:
114
115
1/ If possible, don't use the configure arguments --with-python-prefix
116
and --with-python-exec-prefix; the configure script is able to guess
117
the correct values from you python installation.
118
119
2/ If you have more than one Python version installed, use the arguments
120
--with-python (giving it the *full*, *absolute* path to the Python
121
interpreter) and --with-python-version (giving it the corresponding
122
version, like 1.5 or 2.1.)
123
124
Common problems while building psycopg:
125
126
1/ if your compiler does not find some postgres headers try copying all the
127
headers from the postgres _source_ distribution to a single place. Also,
128
if building postgresql from source, make sure to install all headers by
129
the "make install-all-headers" target.
130
131
2/ if you have the same problem with mx.DateTime, try using the source
132
directory again; the install script does not copy all the headers, same
133
way as postgres install procedure does.
134
135
3/ under MacOS X you may need to run the runlib program on the posgres
136
installed libraries before trying to compile psycopg. Also, if you
137
get compilation errors there is a change your python was not compiled
138
correctly and psycopg is grabbing the wrong compile-time options from
139
python's Makefile. try setting the OPT and LDFLAG environment variables
140
to something usefull, as in the next example:
141
142
OPT="-no-cpp-precomp" LDFLAGS="-flat-namespace" ./configure ...
24
143
25
144
Licence
26
145
-------
30
149
the Free Software Foundation; either version 2 of the License, or
31
150
(at your option) any later version. See file COPYING for details.
32
151
33
As a special exception, specific permission is granted for the GPLed code in
34
this distribition to be linked to OpenSSL and PostgreSQL libpq without
35
invoking GPL clause 2(b).
36
37
If you prefer you can use the Zope Database Adapter ZPsycopgDA (i.e., every
38
file inside the ZPsycopgDA directory) under the ZPL license as published on
39
the Zope web site, http://www.zope.org/Resources/ZPL. The ZPL is perfectly
40
compatible with the GPL
41
42
psycopg is distributed in the hope that it will be useful, but WITHOUT ANY
43
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
44
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
45
details.
152
As a special exception, specific permission is granted for the GPLed
153
code in this distribition to be linked to OpenSSL and PostgreSQL libpq
154
without invoking GPL clause 2(b).
155
156
If you prefer you can use the Zope Database Adapter ZPsycopgDA (i.e.,
157
every file inside the ZPsycopgDA directory) user the ZPL license as
158
published on the Zope web site, http://www.zope.org/Resources/ZPL.
159
160
psycopg is distributed in the hope that it will be useful,
161
but WITHOUT ANY WARRANTY; without even the implied warranty of
162
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
163
GNU General Public License for more details.
164
Loggerhead is a web-based interface for Breezy
Version: 2.0.1