source: branches/5.0.x/docs/contents/install.rst @ 940

Last change on this file since 940 was 940, checked in by cito, 15 months ago

Prepare for version 5.0.6

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