diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/ref/contrib/gis/install/index.txt | 10 | ||||
| -rw-r--r-- | docs/ref/contrib/gis/install/postgis.txt | 11 | ||||
| -rw-r--r-- | docs/ref/contrib/postgres/fields.txt | 41 | ||||
| -rw-r--r-- | docs/ref/contrib/postgres/forms.txt | 8 | ||||
| -rw-r--r-- | docs/ref/databases.txt | 24 | ||||
| -rw-r--r-- | docs/releases/1.11.txt | 9 | ||||
| -rw-r--r-- | docs/releases/4.2.txt | 14 | ||||
| -rw-r--r-- | docs/topics/db/transactions.txt | 4 | ||||
| -rw-r--r-- | docs/topics/install.txt | 6 |
10 files changed, 83 insertions, 46 deletions
diff --git a/docs/conf.py b/docs/conf.py index 3e37509337..8bb6530b75 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -174,7 +174,7 @@ pygments_style = "trac" intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "sphinx": ("https://www.sphinx-doc.org/en/master/", None), - "psycopg2": ("https://www.psycopg.org/docs/", None), + "psycopg": ("https://www.psycopg.org/psycopg3/docs/", None), } # Python's docs don't change every week. diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt index 51b3235279..026c64ccd1 100644 --- a/docs/ref/contrib/gis/install/index.txt +++ b/docs/ref/contrib/gis/install/index.txt @@ -429,14 +429,14 @@ Install Django and set up database recommended that you create a :doc:`virtual environment <python:tutorial/venv>` for each project you create. -psycopg2 -~~~~~~~~ +psycopg +~~~~~~~ -The ``psycopg2`` Python module provides the interface between Python and the -PostgreSQL database. ``psycopg2`` can be installed via pip within your Python +The ``psycopg`` Python module provides the interface between Python and the +PostgreSQL database. ``psycopg`` can be installed via pip within your Python virtual environment:: - ...\> py -m pip install psycopg2 + ...\> py -m pip install psycopg .. rubric:: Footnotes .. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from diff --git a/docs/ref/contrib/gis/install/postgis.txt b/docs/ref/contrib/gis/install/postgis.txt index 0c7d20ae84..e469ede4d0 100644 --- a/docs/ref/contrib/gis/install/postgis.txt +++ b/docs/ref/contrib/gis/install/postgis.txt @@ -7,20 +7,25 @@ into a spatial database. :ref:`geosbuild`, :ref:`proj4` and :ref:`gdalbuild` should be installed prior to building PostGIS. You might also need additional libraries, see `PostGIS requirements`_. -The `psycopg2`_ module is required for use as the database adapter when using -GeoDjango with PostGIS. +The `psycopg`_ or `psycopg2`_ module is required for use as the database +adapter when using GeoDjango with PostGIS. On Debian/Ubuntu, you are advised to install the following packages: ``postgresql-x``, ``postgresql-x-postgis-3``, ``postgresql-server-dev-x``, -and ``python3-psycopg2`` (x matching the PostgreSQL version you want to +and ``python3-psycopg3`` (x matching the PostgreSQL version you want to install). Alternately, you can `build from source`_. Consult the platform-specific instructions if you are on :ref:`macos` or :ref:`windows`. .. _PostGIS: https://postgis.net/ +.. _psycopg: https://www.psycopg.org/psycopg3/ .. _psycopg2: https://www.psycopg.org/ .. _PostGIS requirements: https://postgis.net/docs/postgis_installation.html#install_requirements .. _build from source: https://postgis.net/docs/postgis_installation.html#install_short_version +.. versionchanged:: 4.2 + + Support for ``psycopg`` 3.1+ was added. + Post-installation ================= diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt index 2e6ce4253e..34ad06a09a 100644 --- a/docs/ref/contrib/postgres/fields.txt +++ b/docs/ref/contrib/postgres/fields.txt @@ -538,8 +538,8 @@ PostgreSQL. These fields are used to store a range of values; for example the start and end timestamps of an event, or the range of ages an activity is suitable for. -All of the range fields translate to :ref:`psycopg2 Range objects -<psycopg2:adapt-range>` in Python, but also accept tuples as input if no bounds +All of the range fields translate to :ref:`psycopg Range objects +<psycopg:adapt-range>` in Python, but also accept tuples as input if no bounds information is necessary. The default is lower bound included, upper bound excluded, that is ``[)`` (see the PostgreSQL documentation for details about `different bounds`_). The default bounds can be changed for non-discrete range @@ -553,8 +553,8 @@ the ``default_bounds`` argument. Stores a range of integers. Based on an :class:`~django.db.models.IntegerField`. Represented by an ``int4range`` in - the database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in - Python. + the database and a + ``django.db.backends.postgresql.psycopg_any.NumericRange`` in Python. Regardless of the bounds specified when saving the data, PostgreSQL always returns a range in a canonical form that includes the lower bound and @@ -567,8 +567,8 @@ the ``default_bounds`` argument. Stores a range of large integers. Based on a :class:`~django.db.models.BigIntegerField`. Represented by an ``int8range`` - in the database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in - Python. + in the database and a + ``django.db.backends.postgresql.psycopg_any.NumericRange`` in Python. Regardless of the bounds specified when saving the data, PostgreSQL always returns a range in a canonical form that includes the lower bound and @@ -581,8 +581,8 @@ the ``default_bounds`` argument. Stores a range of floating point values. Based on a :class:`~django.db.models.DecimalField`. Represented by a ``numrange`` in - the database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in - Python. + the database and a + ``django.db.backends.postgresql.psycopg_any.NumericRange`` in Python. .. attribute:: DecimalRangeField.default_bounds @@ -592,7 +592,7 @@ the ``default_bounds`` argument. default is lower bound included, upper bound excluded, that is ``[)`` (see the PostgreSQL documentation for details about `different bounds`_). ``default_bounds`` is not used for - :class:`~psycopg2:psycopg2.extras.NumericRange` inputs. + ``django.db.backends.postgresql.psycopg_any.NumericRange`` inputs. ``DateTimeRangeField`` ---------------------- @@ -601,8 +601,8 @@ the ``default_bounds`` argument. Stores a range of timestamps. Based on a :class:`~django.db.models.DateTimeField`. Represented by a ``tstzrange`` in - the database and a :class:`~psycopg2:psycopg2.extras.DateTimeTZRange` in - Python. + the database and a + ``django.db.backends.postgresql.psycopg_any.DateTimeTZRange`` in Python. .. attribute:: DateTimeRangeField.default_bounds @@ -612,7 +612,7 @@ the ``default_bounds`` argument. default is lower bound included, upper bound excluded, that is ``[)`` (see the PostgreSQL documentation for details about `different bounds`_). ``default_bounds`` is not used for - :class:`~psycopg2:psycopg2.extras.DateTimeTZRange` inputs. + ``django.db.backends.postgresql.psycopg_any.DateTimeTZRange`` inputs. ``DateRangeField`` ------------------ @@ -621,7 +621,8 @@ the ``default_bounds`` argument. Stores a range of dates. Based on a :class:`~django.db.models.DateField`. Represented by a ``daterange`` in the - database and a :class:`~psycopg2:psycopg2.extras.DateRange` in Python. + database and a ``django.db.backends.postgresql.psycopg_any.DateRange`` in + Python. Regardless of the bounds specified when saving the data, PostgreSQL always returns a range in a canonical form that includes the lower bound and @@ -655,7 +656,7 @@ We will also use the following example objects:: and ``NumericRange``: - >>> from psycopg2.extras import NumericRange + >>> from django.db.backends.postgresql.psycopg_any import NumericRange Containment functions ~~~~~~~~~~~~~~~~~~~~~ @@ -690,7 +691,7 @@ The ``contained_by`` lookup is also available on the non-range field types: :class:`~django.db.models.DateField`, and :class:`~django.db.models.DateTimeField`. For example:: - >>> from psycopg2.extras import DateTimeTZRange + >>> from django.db.backends.postgresql.psycopg_any import DateTimeTZRange >>> Event.objects.filter( ... start__contained_by=DateTimeTZRange( ... timezone.now() - datetime.timedelta(hours=1), @@ -864,9 +865,9 @@ Defining your own range types ----------------------------- PostgreSQL allows the definition of custom range types. Django's model and form -field implementations use base classes below, and psycopg2 provides a -:func:`~psycopg2:psycopg2.extras.register_range` to allow use of custom range -types. +field implementations use base classes below, and ``psycopg`` provides a +:func:`~psycopg:psycopg.types.range.register_range` to allow use of custom +range types. .. class:: RangeField(**options) @@ -878,7 +879,7 @@ types. .. attribute:: range_type - The psycopg2 range type to use. + The range type to use. .. attribute:: form_field @@ -895,7 +896,7 @@ types. .. attribute:: range_type - The psycopg2 range type to use. + The range type to use. Range operators --------------- diff --git a/docs/ref/contrib/postgres/forms.txt b/docs/ref/contrib/postgres/forms.txt index e5d597655f..8f9dd449d1 100644 --- a/docs/ref/contrib/postgres/forms.txt +++ b/docs/ref/contrib/postgres/forms.txt @@ -173,7 +173,7 @@ not greater than the upper bound. All of these fields use .. class:: IntegerRangeField Based on :class:`~django.forms.IntegerField` and translates its input into - :class:`~psycopg2:psycopg2.extras.NumericRange`. Default for + ``django.db.backends.postgresql.psycopg_any.NumericRange``. Default for :class:`~django.contrib.postgres.fields.IntegerRangeField` and :class:`~django.contrib.postgres.fields.BigIntegerRangeField`. @@ -183,7 +183,7 @@ not greater than the upper bound. All of these fields use .. class:: DecimalRangeField Based on :class:`~django.forms.DecimalField` and translates its input into - :class:`~psycopg2:psycopg2.extras.NumericRange`. Default for + ``django.db.backends.postgresql.psycopg_any.NumericRange``. Default for :class:`~django.contrib.postgres.fields.DecimalRangeField`. ``DateTimeRangeField`` @@ -192,7 +192,7 @@ not greater than the upper bound. All of these fields use .. class:: DateTimeRangeField Based on :class:`~django.forms.DateTimeField` and translates its input into - :class:`~psycopg2:psycopg2.extras.DateTimeTZRange`. Default for + ``django.db.backends.postgresql.psycopg_any.DateTimeTZRange``. Default for :class:`~django.contrib.postgres.fields.DateTimeRangeField`. ``DateRangeField`` @@ -201,7 +201,7 @@ not greater than the upper bound. All of these fields use .. class:: DateRangeField Based on :class:`~django.forms.DateField` and translates its input into - :class:`~psycopg2:psycopg2.extras.DateRange`. Default for + ``django.db.backends.postgresql.psycopg_any.DateRange``. Default for :class:`~django.contrib.postgres.fields.DateRangeField`. Widgets diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 79b0386e1a..d62adbe832 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -114,11 +114,21 @@ below for information on how to set up your database correctly. PostgreSQL notes ================ -Django supports PostgreSQL 12 and higher. `psycopg2`_ 2.8.4 or higher is -required, though the latest release is recommended. +Django supports PostgreSQL 12 and higher. `psycopg`_ 3.1+ or `psycopg2`_ 2.8.4+ +is required, though the latest `psycopg`_ 3.1+ is recommended. +.. _psycopg: https://www.psycopg.org/psycopg3/ .. _psycopg2: https://www.psycopg.org/ +.. note:: + + Support for ``psycopg2`` is likely to be deprecated and removed at some + point in the future. + +.. versionchanged:: 4.2 + + Support for ``psycopg`` 3.1+ was added. + .. _postgresql-connection-settings: PostgreSQL connection settings @@ -199,12 +209,12 @@ level`_. If you need a higher isolation level such as ``REPEATABLE READ`` or ``SERIALIZABLE``, set it in the :setting:`OPTIONS` part of your database configuration in :setting:`DATABASES`:: - import psycopg2.extensions + from django.db.backends.postgresql.psycopg_any import IsolationLevel DATABASES = { # ... 'OPTIONS': { - 'isolation_level': psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE, + 'isolation_level': IsolationLevel.SERIALIZABLE, }, } @@ -216,6 +226,10 @@ configuration in :setting:`DATABASES`:: .. _isolation level: https://www.postgresql.org/docs/current/transaction-iso.html +.. versionchanged:: 4.2 + + ``IsolationLevel`` was added. + Indexes for ``varchar`` and ``text`` columns -------------------------------------------- @@ -244,7 +258,7 @@ Server-side cursors When using :meth:`QuerySet.iterator() <django.db.models.query.QuerySet.iterator>`, Django opens a :ref:`server-side -cursor <psycopg2:server-side-cursors>`. By default, PostgreSQL assumes that +cursor <psycopg:server-side-cursors>`. By default, PostgreSQL assumes that only the first 10% of the results of cursor queries will be fetched. The query planner spends less time planning the query and starts returning results faster, but this could diminish performance if more than 10% of the results are diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt index 5da81cd739..50b78305d4 100644 --- a/docs/releases/1.11.txt +++ b/docs/releases/1.11.txt @@ -256,10 +256,11 @@ Database backends * Added the :setting:`TEST['TEMPLATE'] <TEST_TEMPLATE>` setting to let PostgreSQL users specify a template for creating the test database. -* :meth:`.QuerySet.iterator()` now uses :ref:`server-side cursors - <psycopg2:server-side-cursors>` on PostgreSQL. This feature transfers some of - the worker memory load (used to hold query results) to the database and might - increase database memory usage. +* :meth:`.QuerySet.iterator()` now uses `server-side cursors`_ on PostgreSQL. + This feature transfers some of the worker memory load (used to hold query + results) to the database and might increase database memory usage. + + .. _server-side cursors: https://www.psycopg.org/docs/usage.html#server-side-cursors * Added MySQL support for the ``'isolation_level'`` option in :setting:`OPTIONS` to allow specifying the :ref:`transaction isolation level diff --git a/docs/releases/4.2.txt b/docs/releases/4.2.txt index 3abe03ef85..077762275a 100644 --- a/docs/releases/4.2.txt +++ b/docs/releases/4.2.txt @@ -26,6 +26,20 @@ and only officially support the latest release of each series. What's new in Django 4.2 ======================== +Psycopg 3 support +----------------- + +Django now supports `psycopg`_ version 3.1 or higher. To update your code, +install the `psycopg library`_, you don't need to change the +:setting:`ENGINE <DATABASE-ENGINE>` as ``django.db.backends.postgresql`` +supports both libraries. + +Support for ``psycopg2`` is likely to be deprecated and removed at some point +in the future. + +.. _psycopg: https://www.psycopg.org/psycopg3/ +.. _psycopg library: https://pypi.org/project/psycopg/ + Minor features -------------- diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index d0b67b86f4..b41c9fa758 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -397,8 +397,8 @@ tasks, etc.), this should be fine. If it's not (if your follow-up action is so critical that its failure should mean the failure of the transaction itself), then you don't want to use the :func:`on_commit` hook. Instead, you may want `two-phase commit`_ such as the :ref:`psycopg Two-Phase Commit protocol support -<psycopg2:tpc>` and the :pep:`optional Two-Phase Commit Extensions in the -Python DB-API specification <249#optional-two-phase-commit-extensions>`. +<psycopg:two-phase-commit>` and the :pep:`optional Two-Phase Commit Extensions +in the Python DB-API specification <249#optional-two-phase-commit-extensions>`. Callbacks are not run until autocommit is restored on the connection following the commit (because otherwise any queries done in a callback would open an diff --git a/docs/topics/install.txt b/docs/topics/install.txt index 1590da8906..bbc74bd4e3 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -79,8 +79,9 @@ databases with Django. In addition to a database backend, you'll need to make sure your Python database bindings are installed. -* If you're using PostgreSQL, you'll need the `psycopg2`_ package. Refer to the - :ref:`PostgreSQL notes <postgresql-notes>` for further details. +* If you're using PostgreSQL, you'll need the `psycopg`_ or `psycopg2`_ + package. Refer to the :ref:`PostgreSQL notes <postgresql-notes>` for further + details. * If you're using MySQL or MariaDB, you'll need a :ref:`DB API driver <mysql-db-api-drivers>` like ``mysqlclient``. See :ref:`notes for the MySQL @@ -111,6 +112,7 @@ database queries, Django will need permission to create a test database. .. _PostgreSQL: https://www.postgresql.org/ .. _MariaDB: https://mariadb.org/ .. _MySQL: https://www.mysql.com/ +.. _psycopg: https://www.psycopg.org/psycopg3/ .. _psycopg2: https://www.psycopg.org/ .. _SQLite: https://www.sqlite.org/ .. _cx_Oracle: https://oracle.github.io/python-cx_Oracle/ |