source: trunk/docs/contents/install.rst @ 710

Last change on this file since 710 was 710, checked in by cito, 4 years ago

Port all doc changes from 4.x branch to trunk

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