Docs changes.

docs/conf.py

@@ -174,7 +174,7 @@ def django_release():
 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.

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

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.x``, ``postgresql-x.x-postgis``, ``postgresql-server-dev-x.x``,
-and ``python-psycopg2`` (x.x matching the PostgreSQL version you want to
+and ``python-psycopg3`` (x.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
 =================
 

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
 ---------------

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

docs/ref/databases.txt

@@ -114,11 +114,16 @@ 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 releases is recommended.
 
+.. _psycopg: https://www.psycopg.org/psycopg3/
 .. _psycopg2: https://www.psycopg.org/
 
+.. versionchanged:: 4.2
+
+    Support for ``psycopg`` 3.1+ was added.
+
 .. _postgresql-connection-settings:
 
 PostgreSQL connection settings
@@ -199,12 +204,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 +221,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 +253,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

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

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 aim 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
 --------------
 

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

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/