mirror of
https://github.com/psycopg/psycopg2.git
synced 2024-09-21 11:18:49 +03:00
Merge branch 'docs/quick-start'
This commit is contained in:
Daniele Varrazzo
commit
90e8c80ed1
|
|
@ -8,27 +8,117 @@ Installation
|
||||||
Psycopg is a PostgreSQL_ adapter for the Python_ programming language. It is a
|
Psycopg is a PostgreSQL_ adapter for the Python_ programming language. It is a
|
||||||
wrapper for the libpq_, the official PostgreSQL client library.
|
wrapper for the libpq_, the official PostgreSQL client library.
|
||||||
|
|
||||||
The `psycopg2` package is the current mature implementation of the adapter: it
|
|
||||||
is a C extension and as such it is only compatible with CPython_. If you want
|
|
||||||
to use Psycopg on a different Python implementation (PyPy, Jython, IronPython)
|
|
||||||
there is a couple of alternative:
|
|
||||||
|
|
||||||
- a `Ctypes port`__, but it is not as mature as the C implementation yet
|
|
||||||
and it is not as feature-complete;
|
|
||||||
|
|
||||||
- a `CFFI port`__ which is currently more used and reported more efficient on
|
|
||||||
PyPy, but please be careful of its version numbers because they are not
|
|
||||||
aligned to the official psycopg2 ones and some features may differ.
|
|
||||||
|
|
||||||
.. _PostgreSQL: https://www.postgresql.org/
|
.. _PostgreSQL: https://www.postgresql.org/
|
||||||
.. _Python: https://www.python.org/
|
.. _Python: https://www.python.org/
|
||||||
.. _libpq: https://www.postgresql.org/docs/current/static/libpq.html
|
|
||||||
.. _CPython: https://en.wikipedia.org/wiki/CPython
|
|
||||||
.. _Ctypes: https://docs.python.org/library/ctypes.html
|
|
||||||
.. __: https://github.com/mvantellingen/psycopg2-ctypes
|
|
||||||
.. __: https://github.com/chtd/psycopg2cffi
|
|
||||||
|
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: Install; from PyPI
|
||||||
|
single: Install; wheel
|
||||||
|
single: Wheel
|
||||||
|
|
||||||
|
.. _binary-packages:
|
||||||
|
|
||||||
|
Quick Install
|
||||||
|
-------------
|
||||||
|
|
||||||
|
For most operating systems, the quickest way to install Psycopg is using the
|
||||||
|
wheel_ package available on PyPI_:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ pip install psycopg2-binary
|
||||||
|
|
||||||
|
This will install a pre-compiled binary version of the module which does not
|
||||||
|
require the build or runtime prerequisites described below. Make sure to use
|
||||||
|
an up-date-date version of :program:`pip` (you can upgrade it using something
|
||||||
|
like ``pip install -U pip``).
|
||||||
|
|
||||||
|
You may then import the ``psycopg`` package, as usual:
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
import psycopg
|
||||||
|
|
||||||
|
# Connect to your postgres DB
|
||||||
|
conn = psycopg.connect("dbname=test user=postgres")
|
||||||
|
|
||||||
|
# Open a cursor to perform database operations
|
||||||
|
cur = conn.cursor()
|
||||||
|
|
||||||
|
# Execute a query
|
||||||
|
cur.execute("SELECT * FROM my_data");
|
||||||
|
|
||||||
|
# Retrieve query results
|
||||||
|
records = cur.fetchall()
|
||||||
|
|
||||||
|
.. _PyPI: https://pypi.org/project/psycopg2-binary/
|
||||||
|
.. _wheel: https://pythonwheels.com/
|
||||||
|
|
||||||
|
|
||||||
|
psycopg vs psycopg-binary
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The ``psycopg2-binary`` package is meant for beginners to start playing
|
||||||
|
with Python and PostgreSQL without the need to meet the build
|
||||||
|
requirements.
|
||||||
|
|
||||||
|
If you are the maintainer of a published package depending on `!psycopg2`
|
||||||
|
you shouldn't use ``psycopg2-binary`` as a module dependency. **For
|
||||||
|
production use you are advised to use the source distribution.**
|
||||||
|
|
||||||
|
The binary packages come with their own versions of a few C libraries,
|
||||||
|
among which ``libpq`` and ``libssl``, which will be used regardless of other
|
||||||
|
libraries available on the client: upgrading the system libraries will not
|
||||||
|
upgrade the libraries used by `!psycopg2`. Please build `!psycopg2` from
|
||||||
|
source if you want to maintain binary upgradeability.
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
The `!psycopg2` wheel package comes packaged, among the others, with its
|
||||||
|
own ``libssl`` binary. This may create conflicts with other extension
|
||||||
|
modules binding with ``libssl`` as well, for instance with the Python
|
||||||
|
`ssl` module: in some cases, under concurrency, the interaction between
|
||||||
|
the two libraries may result in a segfault. In case of doubts you are
|
||||||
|
advised to use a package built from source.
|
||||||
|
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: Install; disable wheel
|
||||||
|
single: Wheel; disable
|
||||||
|
|
||||||
|
.. _disable-wheel:
|
||||||
|
|
||||||
|
Change in binary packages between Psycopg 2.7 and 2.8
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
In version 2.7.x, :command:`pip install psycopg2` would have tried to install
|
||||||
|
automatically the binary package of Psycopg. Because of concurrency problems
|
||||||
|
binary packages have displayed, ``psycopg2-binary`` has become a separate
|
||||||
|
package, and from 2.8 it has become the only way to install the binary
|
||||||
|
package.
|
||||||
|
|
||||||
|
If you are using Psycopg 2.7 and you want to disable the use of wheel binary
|
||||||
|
packages, relying on the system libraries available on your client, you
|
||||||
|
can use the :command:`pip` |--no-binary option|__, e.g.:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ pip install --no-binary :all: psycopg2
|
||||||
|
|
||||||
|
.. |--no-binary option| replace:: ``--no-binary`` option
|
||||||
|
.. __: https://pip.pypa.io/en/stable/reference/pip_install/#install-no-binary
|
||||||
|
|
||||||
|
which can be specified in your :file:`requirements.txt` files too, e.g. use:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
psycopg2>=2.7,<2.8 --no-binary psycopg2
|
||||||
|
|
||||||
|
to use the last bugfix release of the `!psycopg2` 2.7 package, specifying to
|
||||||
|
always compile it from source. Of course in this case you will have to meet
|
||||||
|
the :ref:`build prerequisites <build-prerequisites>`.
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
.. index::
|
||||||
single: Prerequisites
|
single: Prerequisites
|
||||||
|
|
@ -130,101 +220,6 @@ which is OS-dependent (for instance setting a suitable
|
||||||
to connect to.
|
to connect to.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
|
||||||
single: Install; from PyPI
|
|
||||||
single: Install; wheel
|
|
||||||
single: Wheel
|
|
||||||
|
|
||||||
.. _binary-packages:
|
|
||||||
|
|
||||||
Binary install from PyPI
|
|
||||||
------------------------
|
|
||||||
|
|
||||||
`!psycopg2` is also `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, not requiring the above build or
|
|
||||||
runtime prerequisites.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
The ``psycopg2-binary`` package is meant for beginners to start playing
|
|
||||||
with Python and PostgreSQL without the need to meet the build
|
|
||||||
requirements.
|
|
||||||
|
|
||||||
If you are the maintainer of a published package depending on `!psycopg2`
|
|
||||||
**you shouldn't use 'psycopg2-binary' as a module dependency**. For
|
|
||||||
production use you are advised to use the source distribution.
|
|
||||||
|
|
||||||
|
|
||||||
Make sure to use an up-to-date version of :program:`pip` (you can upgrade it
|
|
||||||
using something like ``pip install -U pip``), then you can run:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ pip install psycopg2-binary
|
|
||||||
|
|
||||||
.. __: PyPI-binary_
|
|
||||||
.. _PyPI-binary: https://pypi.org/project/psycopg2-binary/
|
|
||||||
.. _wheel: https://pythonwheels.com/
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
The binary packages come with their own versions of a few C libraries,
|
|
||||||
among which ``libpq`` and ``libssl``, which will be used regardless of other
|
|
||||||
libraries available on the client: upgrading the system libraries will not
|
|
||||||
upgrade the libraries used by `!psycopg2`. Please build `!psycopg2` from
|
|
||||||
source if you want to maintain binary upgradeability.
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
The `!psycopg2` wheel package comes packaged, among the others, with its
|
|
||||||
own ``libssl`` binary. This may create conflicts with other extension
|
|
||||||
modules binding with ``libssl`` as well, for instance with the Python
|
|
||||||
`ssl` module: in some cases, under concurrency, the interaction between
|
|
||||||
the two libraries may result in a segfault. In case of doubts you are
|
|
||||||
advised to use a package built from source.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
|
||||||
single: Install; disable wheel
|
|
||||||
single: Wheel; disable
|
|
||||||
|
|
||||||
.. _disable-wheel:
|
|
||||||
|
|
||||||
Change in binary packages between Psycopg 2.7 and 2.8
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
In version 2.7.x, :command:`pip install psycopg2` would have tried to install
|
|
||||||
automatically the binary package of Psycopg. Because of concurrency problems
|
|
||||||
binary packages have displayed, ``psycopg2-binary`` has become a separate
|
|
||||||
package, and from 2.8 it has become the only way to install the binary
|
|
||||||
package.
|
|
||||||
|
|
||||||
If you are using Psycopg 2.7 and you want to disable the use of wheel binary
|
|
||||||
packages, relying on the system libraries available on your client, you
|
|
||||||
can use the :command:`pip` |--no-binary option|__, e.g.:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ pip install --no-binary :all: psycopg2
|
|
||||||
|
|
||||||
.. |--no-binary option| replace:: ``--no-binary`` option
|
|
||||||
.. __: https://pip.pypa.io/en/stable/reference/pip_install/#install-no-binary
|
|
||||||
|
|
||||||
which can be specified in your :file:`requirements.txt` files too, e.g. use:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
psycopg2>=2.7,<2.8 --no-binary psycopg2
|
|
||||||
|
|
||||||
to use the last bugfix release of the `!psycopg2` 2.7 package, specifying to
|
|
||||||
always compile it from source. Of course in this case you will have to meet
|
|
||||||
the :ref:`build prerequisites <build-prerequisites>`.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
.. index::
|
||||||
single: setup.py
|
single: setup.py
|
||||||
single: setup.cfg
|
single: setup.cfg
|
||||||
|
|
@ -286,6 +281,29 @@ order to create a debug package:
|
||||||
.. __: https://pypi.org/project/psycopg2/#files
|
.. __: https://pypi.org/project/psycopg2/#files
|
||||||
|
|
||||||
|
|
||||||
|
Non-standard Python Implementation
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The `psycopg2` package is the current mature implementation of the adapter: it
|
||||||
|
is a C extension and as such it is only compatible with CPython_. If you want
|
||||||
|
to use Psycopg on a different Python implementation (PyPy, Jython, IronPython)
|
||||||
|
there is a couple of alternative:
|
||||||
|
|
||||||
|
- a `Ctypes port`__, but it is not as mature as the C implementation yet
|
||||||
|
and it is not as feature-complete;
|
||||||
|
|
||||||
|
- a `CFFI port`__ which is currently more used and reported more efficient on
|
||||||
|
PyPy, but please be careful of its version numbers because they are not
|
||||||
|
aligned to the official psycopg2 ones and some features may differ.
|
||||||
|
|
||||||
|
.. _PostgreSQL: https://www.postgresql.org/
|
||||||
|
.. _Python: https://www.python.org/
|
||||||
|
.. _libpq: https://www.postgresql.org/docs/current/static/libpq.html
|
||||||
|
.. _CPython: https://en.wikipedia.org/wiki/CPython
|
||||||
|
.. _Ctypes: https://docs.python.org/library/ctypes.html
|
||||||
|
.. __: https://github.com/mvantellingen/psycopg2-ctypes
|
||||||
|
.. __: https://github.com/chtd/psycopg2cffi
|
||||||
|
|
||||||
|
|
||||||
.. index::
|
.. index::
|
||||||
single: tests
|
single: tests
|
||||||
|
|
@ -314,7 +332,6 @@ setting the environment variables:
|
||||||
The database should already exist before running the tests.
|
The database should already exist before running the tests.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. _other-problems:
|
.. _other-problems:
|
||||||
|
|
||||||
If you still have problems
|
If you still have problems
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user