source: trunk/docs/install.txt @ 362

Last change on this file since 362 was 362, checked in by cito, 11 years ago

Typo.

File size: 6.6 KB
Line 
1=====================
2PyGreSQL Installation
3=====================
4
5.. sectnum::
6.. contents:: Contents
7
8
9General
10=======
11
12You must first have installed Python and PostgreSQL on your system.
13If you want to access remote database only, you don't need to install
14the full PostgreSQL server, but only the C interface (libpq). If you
15are on Windows, make sure that the directory with libpq.dll is in your
16``PATH`` environment variable.
17
18The current version of PyGreSQL has been tested with Python 2.5 and
19PostGreSQL 8.3. Older version should work as well, but you will need
20at least Python 2.3 and PostgreSQL 7.4.
21
22PyGreSQL will be installed as three modules, a dynamic module called
23_pg.pyd, and two pure Python wrapper modules called pg.py and pgdb.py.
24All three files will be installed directly into the Python site-packages
25directory. To uninstall PyGreSQL, simply remove these three files again.
26
27
28Installing from a Binary Distribution
29=====================================
30
31This is the easiest way to install PyGreSQL.
32
33You can currently download PyGreSQL as Linux RPM, NetBSD package and Windows
34installer. Make sure the required Python version of the binary package matches
35the Python version you have installed.
36
37Install the package as usual on your system.
38
39Note that the documentation is currently only included in the source package.
40
41
42Installing from Source
43======================
44
45If you want to install PyGreSQL from Source, or there is no binary
46package available for your platform, follow these instructions.
47
48Make sure the Python header files and PostgreSQL client and server header
49files are installed. These come usually with the "devel" packages on Unix
50systems and the installer executables on Windows systems.
51
52If you are using a precompiled PostgreSQL, you will also need the pg_config
53tool. This is usually also part of the "devel" package on Unix, and will be
54installed as part of the database server feature on Windows systems.
55
56Building and installing with Distutils
57--------------------------------------
58
59You can build and install PyGreSQL using
60`Distutils <http://docs.python.org/install/>`_.
61
62Download and unpack the PyGreSQL source tarball if you haven't already done so.
63
64Type the following commands to build and install PyGreSQL::
65
66    python setup.py build
67    python setup.py install
68
69If you are using `MinGW <http://www.mingw.org>`_ to build PyGreSQL under
70Microsoft Windows, please note that Python newer version 2.3 is using msvcr71
71instead of msvcrt as its common runtime library. You can allow for that by
72editing the file ``%MinGWpath%/lib/gcc/%MinGWversion%/specs`` and changing
73the entry that reads ``-lmsvcrt`` to ``-lmsvcr71``. You may also need to copy
74``libpq.lib`` to ``libpq.a`` in the PostgreSQL ``lib`` directory. Then use
75the following command to build and install PyGreSQL::
76
77    python setup.py build -c mingw32 install
78
79Now you should be ready to use PyGreSQL.
80
81Compiling Manually
82------------------
83
84The source file for compiling the dynamic module is called pgmodule.c.
85You have two options. You can compile PyGreSQL as a stand-alone module
86or you can build it into the Python interpreter.
87
88Stand-Alone
89-----------
90
91* In the directory containing ``pgmodule.c``, run the following command::
92
93    cc -fpic -shared -o _pg.so -I$PYINC -I$PGINC -I$PSINC -L$PGLIB -lpq pgmodule.c
94
95  where you have to set::
96
97    PYINC = path to the Python include files
98            (usually something like /usr/include/python)
99    PGINC = path to the PostgreSQL client include files
100            (something like /usr/include/pgsql or /usr/include/postgresql)
101    PSINC = path to the PostgreSQL server include files
102            (like /usr/include/pgsql/server or /usr/include/postgresql/server)
103    PGLIB = path to the PostgreSQL object code libraries (usually /usr/lib)
104
105  If you are not sure about the above paths, try something like::
106
107    PYINC=`find /usr -name Python.h`
108    PGINC=`find /usr -name libpq-fe.h`
109    PSINC=`find /usr -name postgres.h`
110    PGLIB=`find /usr -name libpq.so`
111
112  If you have the ``pg_config`` tool installed, you can set::
113
114    PGINC=`pg_config --includedir`
115    PSINC=`pg_config --includedir-server`
116    PGLIB=`pg_config --libdir`
117
118  Some options may be added to this line::
119
120    -DNO_DEF_VAR   no default variables support
121    -DNO_DIRECT    no direct access methods
122    -DNO_LARGE     no large object support
123    -DNO_PQSOCKET  if running an older PostgreSQL
124
125  Define ``NO_PQSOCKET`` if you are using a version of PostgreSQL before 6.4
126  that does not have the PQsocket function. The other options will be
127  described in the next sections.
128
129  On some systems you may need to include ``-lcrypt`` in the list of libraries
130  to make it compile.
131
132* Test the new module. Something like the following should work::
133
134    $ python
135
136    >>> import _pg
137    >>> db = _pg.connect('thilo','localhost')
138    >>> db.query("INSERT INTO test VALUES ('ping','pong')")
139    18304
140    >>> db.query("SELECT * FROM test")
141    eins|zwei
142    ----+----
143    ping|pong
144    (1 row)
145
146* Finally, move the ``_pg.so``, ``pg.py``, and ``pgdb.py`` to a directory in
147  your ``PYTHONPATH``. A good place would be ``/usr/lib/python/site-packages``
148  if your Python modules are in ``/usr/lib/python``.
149
150Built-in to Python interpreter
151------------------------------
152
153* Find the directory where your ``Setup`` file lives (usually in the ``Modules``
154  subdirectory) in the Python source hierarchy and copy or symlink the
155  ``pgmodule.c`` file there.
156
157* Add the following line to your 'Setup' file::
158
159    _pg  pgmodule.c -I$PGINC -I$PSINC -L$PGLIB -lpq
160
161  where::
162
163    PGINC = path to the PostgreSQL client include files (see above)
164    PSINC = path to the PostgreSQL server include files (see above)
165    PGLIB = path to the PostgreSQL object code libraries (see above)
166
167  Some options may be added to this line::
168
169    -DNO_DEF_VAR   no default variables support
170    -DNO_DIRECT    no direct access methods
171    -DNO_LARGE     no large object support
172    -DNO_PQSOCKET  if running an older PostgreSQL (see above)
173
174  On some systems you may need to include ``-lcrypt`` in the list of libraries
175  to make it compile.
176
177* If you want a shared module, make sure that the ``shared`` keyword is
178  uncommented and add the above line below it. You used to need to install
179  your shared modules with ``make sharedinstall`` but this no longer seems
180  to be true.
181
182* Copy ``pg.py`` to the lib directory where the rest of your modules are.
183  For example, that's ``/usr/local/lib/Python`` on my system.
184
185* Rebuild Python from the root directory of the Python source hierarchy by
186  running ``make -f Makefile.pre.in boot`` and ``make && make install``.
187
188* For more details read the documentation at the top of ``Makefile.pre.in``.
Note: See TracBrowser for help on using the repository browser.