mirror of
https://github.com/psycopg/psycopg2.git
synced 2025-06-03 12:43:07 +03:00
Document installation from wheel packages
This commit is contained in:
Daniele Varrazzo
parent
82adf8a162
commit
30efe59af7
13
README.rst
13
README.rst
|
|
@ -29,8 +29,14 @@ Documentation is included in the 'doc' directory and is `available online`__.
|
||||||
Installation
|
Installation
|
||||||
------------
|
------------
|
||||||
|
|
||||||
If all the dependencies are met (i.e. you have the Python and libpq
|
If your ``pip`` version supports wheel_ packages it should be possible to
|
||||||
development packages installed in your system) the standard::
|
install a binary version of Psycopg including all the dependencies. Just run::
|
||||||
|
|
||||||
|
pip install psycopg2
|
||||||
|
|
||||||
|
If you want to build Psycopg from source you will need some prerequisite (a C
|
||||||
|
compiler, Python and libpq development packages). If you have what you need
|
||||||
|
the standard::
|
||||||
|
|
||||||
python setup.py build
|
python setup.py build
|
||||||
sudo python setup.py install
|
sudo python setup.py install
|
||||||
|
|
@ -38,7 +44,8 @@ development packages installed in your system) the standard::
|
||||||
should work no problem. In case you have any problem check the 'install' and
|
should work no problem. In case you have any problem check the 'install' and
|
||||||
the 'faq' documents in the docs or online__.
|
the 'faq' documents in the docs or online__.
|
||||||
|
|
||||||
.. __: http://initd.org/psycopg/docs/install.html
|
.. _wheel: http://pythonwheels.com/
|
||||||
|
.. __: http://initd.org/psycopg/docs/install.html#install-from-source
|
||||||
|
|
||||||
For any other resource (source code repository, bug tracker, mailing list)
|
For any other resource (source code repository, bug tracker, mailing list)
|
||||||
please check the `project homepage`__.
|
please check the `project homepage`__.
|
||||||
|
|
|
||||||
|
|
@ -30,96 +30,26 @@ The current `!psycopg2` implementation supports:
|
||||||
.. __: https://github.com/mvantellingen/psycopg2-ctypes
|
.. __: https://github.com/mvantellingen/psycopg2-ctypes
|
||||||
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
`!psycopg2` usually depends at runtime on the libpq dynamic library.
|
|
||||||
However it can connect to PostgreSQL servers of any supported version,
|
|
||||||
independently of the version of the libpq used: just install the most
|
|
||||||
recent libpq version or the most practical, without trying to match it to
|
|
||||||
the version of the PostgreSQL server you will have to connect to.
|
|
||||||
|
|
||||||
|
|
||||||
Installation
|
|
||||||
============
|
|
||||||
|
|
||||||
If possible, and usually it is, please :ref:`install Psycopg from a package
|
|
||||||
<install-from-package>` available for your distribution or operating system.
|
|
||||||
|
|
||||||
Compiling from source is a very easy task, however `!psycopg2` is a C
|
|
||||||
extension module and as such it requires a few more things in place respect to
|
|
||||||
a pure Python module. So, if you don't have experience compiling Python
|
|
||||||
extension packages, *above all if you are a Windows or a Mac OS user*, please
|
|
||||||
use a pre-compiled package and go straight to the :ref:`module usage <usage>`
|
|
||||||
avoid bothering with the gory details.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Regardless of the way `!psycopg2` is installed, at runtime it will need to
|
|
||||||
use the libpq_ library. `!psycopg2` relies on the host OS to find the
|
|
||||||
library file (usually ``libpq.so`` or ``libpq.dll``): if the library is
|
|
||||||
installed in a standard location there is usually no problem; if the
|
|
||||||
library is in a non-standard location you will have to tell somehow
|
|
||||||
psycopg how to find it, which is OS-dependent (for instance setting a
|
|
||||||
suitable :envvar:`LD_LIBRARY_PATH` on Linux).
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. _install-from-package:
|
|
||||||
|
|
||||||
Install from a package
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
.. index::
|
.. index::
|
||||||
pair: Install; Linux
|
single: Install; from PyPI
|
||||||
|
|
||||||
**Linux**
|
Binary install from PyPI
|
||||||
Psycopg is available already packaged in many Linux distributions: look
|
------------------------
|
||||||
for a package such as ``python-psycopg2`` using the package manager of
|
|
||||||
your choice.
|
|
||||||
|
|
||||||
On Debian, Ubuntu and other deb-based distributions you should just need::
|
`!psycopg2` is `available on PyPI`__ in the form of wheel_ packages for the
|
||||||
|
most common platform (Linux, OSX, Windows): this should make you able to
|
||||||
|
install a binary version of the module including all the dependencies simply
|
||||||
|
using::
|
||||||
|
|
||||||
sudo apt-get install python-psycopg2
|
pip install psycopg2
|
||||||
|
|
||||||
to install the package with all its dependencies.
|
Make sure to use an up-to-date version of :program:`pip` (you can upgrade it
|
||||||
|
using something like ``pip install -U pip``)
|
||||||
|
|
||||||
|
.. __: PyPI_
|
||||||
.. index::
|
.. _PyPI: https://pypi.python.org/pypi/psycopg2/
|
||||||
pair: Install; Mac OS X
|
.. _wheel: http://pythonwheels.com/
|
||||||
|
|
||||||
**Mac OS X**
|
|
||||||
Psycopg is available as a `fink package`__ in the *unstable* tree: you may
|
|
||||||
install it with::
|
|
||||||
|
|
||||||
fink install psycopg2-py27
|
|
||||||
|
|
||||||
.. __: http://pdb.finkproject.org/pdb/package.php/psycopg2-py27
|
|
||||||
|
|
||||||
The library is also available on `MacPorts`__ try::
|
|
||||||
|
|
||||||
sudo port install py27-psycopg2
|
|
||||||
|
|
||||||
.. __: http://www.macports.org/
|
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
|
||||||
pair: Install; Windows
|
|
||||||
|
|
||||||
**Microsoft Windows**
|
|
||||||
There are two options to install a precompiled `psycopg2` package under windows:
|
|
||||||
|
|
||||||
**Option 1:** Using `pip`__ (Included in python 2.7.9+ and python 3.4+)
|
|
||||||
and a binary wheel package. Launch windows' command prompt (`cmd.exe`)
|
|
||||||
and execute the following command::
|
|
||||||
|
|
||||||
pip install psycopg2
|
|
||||||
|
|
||||||
.. __: https://pip.pypa.io/en/stable/installing/
|
|
||||||
|
|
||||||
**Option 2:** Jason Erickson maintains a packaged `Windows port of Psycopg`__ with
|
|
||||||
installation executable. Download. Double click. Done.
|
|
||||||
|
|
||||||
.. __: http://www.stickpeople.com/projects/python/win-psycopg/
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -131,11 +61,23 @@ Install from a package
|
||||||
Install from source
|
Install from source
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
|
.. _source-package:
|
||||||
|
|
||||||
|
You can download a copy of Psycopg source files from the `Psycopg download
|
||||||
|
page`__ or from PyPI_.
|
||||||
|
|
||||||
|
.. __: http://initd.org/psycopg/download/
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _build-prerequisites:
|
||||||
|
|
||||||
|
Build prerequisites
|
||||||
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
These notes illustrate how to compile Psycopg on Linux. If you want to compile
|
These notes illustrate how to compile Psycopg on Linux. If you want to compile
|
||||||
Psycopg on other platforms you may have to adjust some details accordingly.
|
Psycopg on other platforms you may have to adjust some details accordingly.
|
||||||
|
|
||||||
.. _requirements:
|
|
||||||
|
|
||||||
Psycopg is a C wrapper to the libpq PostgreSQL client library. To install it
|
Psycopg is a C wrapper to the libpq PostgreSQL client library. To install it
|
||||||
from sources you will need:
|
from sources you will need:
|
||||||
|
|
||||||
|
|
@ -158,9 +100,22 @@ from sources you will need:
|
||||||
``/usr/lib/postgresql/X.Y/bin/``) and add it to the :envvar:`PATH`::
|
``/usr/lib/postgresql/X.Y/bin/``) and add it to the :envvar:`PATH`::
|
||||||
|
|
||||||
$ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH
|
$ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH
|
||||||
|
|
||||||
You only need it to compile and install `!psycopg2`, not for its regular
|
You only need :program:`pg_config` to compile `!psycopg2`, not for its
|
||||||
usage.
|
regular usage.
|
||||||
|
|
||||||
|
|
||||||
|
Runtime requirements
|
||||||
|
^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Unless you compile `!psycopg2` as a static library, or you install it from a
|
||||||
|
self-contained wheel package, it will need the libpq_ library at runtime
|
||||||
|
(usually distributed in a ``libpq.so`` or ``libpq.dll`` file). `!psycopg2`
|
||||||
|
relies on the host OS to find the library if the library is installed in a
|
||||||
|
standard location there is usually no problem; if the library is in a
|
||||||
|
non-standard location you will have to tell somehow Psycopg how to find it,
|
||||||
|
which is OS-dependent (for instance setting a suitable
|
||||||
|
:envvar:`LD_LIBRARY_PATH` on Linux).
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
|
@ -170,40 +125,22 @@ from sources you will need:
|
||||||
:program:`ldd`) if the module ``psycopg2/_psycopg.so`` is linked to the
|
:program:`ldd`) if the module ``psycopg2/_psycopg.so`` is linked to the
|
||||||
right ``libpq.so``.
|
right ``libpq.so``.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Whatever version of libpq `!psycopg2` is compiled with, it will be
|
||||||
|
possible to connect to PostgreSQL servers of any supported version: just
|
||||||
|
install the most recent libpq version or the most practical, without
|
||||||
|
trying to match it to the version of the PostgreSQL server you will have
|
||||||
|
to connect to.
|
||||||
|
|
||||||
.. index::
|
|
||||||
single: Install; from PyPI
|
|
||||||
|
|
||||||
.. _package-manager:
|
|
||||||
|
|
||||||
Use a Python package manager
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
If the above requirements are satisfied, you can use :program:`easy_install`,
|
|
||||||
:program:`pip` or whatever the Python package manager of the week::
|
|
||||||
|
|
||||||
$ pip install psycopg2
|
|
||||||
|
|
||||||
Please refer to your package manager documentation about performing a local or
|
|
||||||
global installation, :program:`virtualenv` (fully supported by recent Psycopg
|
|
||||||
versions), using different Python versions and other nuances.
|
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
.. index::
|
||||||
single: setup.py
|
single: setup.py
|
||||||
single: setup.cfg
|
single: setup.cfg
|
||||||
|
|
||||||
.. _source-package:
|
Non-standard builds
|
||||||
|
^^^^^^^^^^^^^^^^^^^
|
||||||
Use the source package
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
You can download a copy of Psycopg source files from the `Psycopg download
|
|
||||||
page`__. Once unpackaged, to compile and install the package you can run::
|
|
||||||
|
|
||||||
$ python setup.py build
|
|
||||||
$ sudo python setup.py install
|
|
||||||
|
|
||||||
If you have less standard requirements such as:
|
If you have less standard requirements such as:
|
||||||
|
|
||||||
|
|
@ -215,43 +152,13 @@ then take a look at the ``setup.cfg`` file.
|
||||||
|
|
||||||
Some of the options available in ``setup.cfg`` are also available as command
|
Some of the options available in ``setup.cfg`` are also available as command
|
||||||
line arguments of the ``build_ext`` sub-command. For instance you can specify
|
line arguments of the ``build_ext`` sub-command. For instance you can specify
|
||||||
an alternate :program:`pg_config` version using::
|
an alternate :program:`pg_config` location using::
|
||||||
|
|
||||||
$ python setup.py build_ext --pg-config /path/to/pg_config build
|
$ python setup.py build_ext --pg-config /path/to/pg_config build
|
||||||
|
|
||||||
Use ``python setup.py build_ext --help`` to get a list of the options
|
Use ``python setup.py build_ext --help`` to get a list of the options
|
||||||
supported.
|
supported.
|
||||||
|
|
||||||
.. __: http://initd.org/psycopg/download/
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
|
||||||
single: tests
|
|
||||||
|
|
||||||
.. _test-suite:
|
|
||||||
|
|
||||||
Running the test suite
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The included ``Makefile`` allows to run all the tests included in the
|
|
||||||
distribution. Just run::
|
|
||||||
|
|
||||||
make
|
|
||||||
make check
|
|
||||||
|
|
||||||
The tests run against a database called ``psycopg2_test`` on UNIX socket and
|
|
||||||
the standard port. You can configure a different database to run the test by
|
|
||||||
setting the environment variables:
|
|
||||||
|
|
||||||
- :envvar:`PSYCOPG2_TESTDB`
|
|
||||||
- :envvar:`PSYCOPG2_TESTDB_HOST`
|
|
||||||
- :envvar:`PSYCOPG2_TESTDB_PORT`
|
|
||||||
- :envvar:`PSYCOPG2_TESTDB_USER`
|
|
||||||
|
|
||||||
The database should already exist before running the tests.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
.. index::
|
||||||
single: debug
|
single: debug
|
||||||
|
|
@ -260,7 +167,7 @@ The database should already exist before running the tests.
|
||||||
.. _debug-build:
|
.. _debug-build:
|
||||||
|
|
||||||
Creating a debug build
|
Creating a debug build
|
||||||
----------------------
|
^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
In case of problems, Psycopg can be configured to emit detailed debug
|
In case of problems, Psycopg can be configured to emit detailed debug
|
||||||
messages, which can be very useful for diagnostics and to report a bug. In
|
messages, which can be very useful for diagnostics and to report a bug. In
|
||||||
|
|
@ -285,6 +192,32 @@ order to create a debug package:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: tests
|
||||||
|
|
||||||
|
.. _test-suite:
|
||||||
|
|
||||||
|
Running the test suite
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
Once `!psycopg2` is installed you can run the test suite to verify it is
|
||||||
|
working correctly. You can run::
|
||||||
|
|
||||||
|
python -c "from psycopg2 import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose
|
||||||
|
|
||||||
|
The tests run against a database called ``psycopg2_test`` on UNIX socket and
|
||||||
|
the standard port. You can configure a different database to run the test by
|
||||||
|
setting the environment variables:
|
||||||
|
|
||||||
|
- :envvar:`PSYCOPG2_TESTDB`
|
||||||
|
- :envvar:`PSYCOPG2_TESTDB_HOST`
|
||||||
|
- :envvar:`PSYCOPG2_TESTDB_PORT`
|
||||||
|
- :envvar:`PSYCOPG2_TESTDB_USER`
|
||||||
|
|
||||||
|
The database should already exist before running the tests.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. _other-problems:
|
.. _other-problems:
|
||||||
|
|
||||||
If you still have problems
|
If you still have problems
|
||||||
|
|
@ -292,7 +225,7 @@ If you still have problems
|
||||||
|
|
||||||
Try the following. *In order:*
|
Try the following. *In order:*
|
||||||
|
|
||||||
- Read again the :ref:`requirements <requirements>`.
|
- Read again the :ref:`build-prerequisites`.
|
||||||
|
|
||||||
- Read the :ref:`FAQ <faq-compile>`.
|
- Read the :ref:`FAQ <faq-compile>`.
|
||||||
|
|
||||||
|
|
@ -306,4 +239,3 @@ Try the following. *In order:*
|
||||||
:envvar:`ARCHFLAGS`. Especially useful from the Starbucks near you.
|
:envvar:`ARCHFLAGS`. Especially useful from the Starbucks near you.
|
||||||
|
|
||||||
.. __: http://mail.postgresql.org/mj/mj_wwwusr/domain=postgresql.org?func=lists-long-full&extra=psycopg
|
.. __: http://mail.postgresql.org/mj/mj_wwwusr/domain=postgresql.org?func=lists-long-full&extra=psycopg
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user