source: trunk/docs/install.rst @ 516

Last change on this file since 516 was 516, checked in by D'Arcy J.M. Cain, 7 years ago

Seems that keyword expansion was never set up on these files.

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