Fixed #33308 -- Added support for psycopg version 3.

Thanks Simon Charette, Tim Graham, and Adam Johnson for reviews.

Co-authored-by: Florian Apolloner <florian@apolloner.eu>
Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

5 files changed, 57 insertions, 37 deletions

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