Fixed #18468 -- Added support for comments on columns and tables.

Thanks Jared Chung, Tom Carrick, David Smith, Nick Pope, and Mariusz
Felisiak for reviews.

Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>
Co-authored-by: Nick Pope <nick@nickpope.me.uk>

6 files changed, 93 insertions, 0 deletions

diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt
index f85c90059d..fa7c633487 100644
--- a/docs/ref/checks.txt
+++ b/docs/ref/checks.txt
@@ -196,6 +196,8 @@ Model fields
 * **fields.W161**: Fixed default value provided.
 * **fields.W162**: ``<database>`` does not support a database index on
   ``<field data type>`` columns.
+* **fields.W163**: ``<database>`` does not support comments on columns
+  (``db_comment``).
 * **fields.E170**: ``BinaryField``’s ``default`` cannot be a string. Use bytes
   content instead.
 * **fields.E180**: ``<database>`` does not support ``JSONField``\s.
@@ -315,6 +317,7 @@ Related fields
   the table name of ``<model>``/``<model>.<field name>``.
 * **fields.W345**: ``related_name`` has no effect on ``ManyToManyField`` with a
   symmetrical relationship, e.g. to "self".
+* **fields.W346**: ``db_comment`` has no effect on ``ManyToManyField``.
 
 Models
 ------
@@ -400,6 +403,8 @@ Models
   expressions.
 * **models.W045**: Check constraint ``<constraint>`` contains ``RawSQL()``
   expression and won't be validated during the model ``full_clean()``.
+* **models.W046**: ``<database>`` does not support comments on tables
+  (``db_table_comment``).
 
 Security
 --------
diff --git a/docs/ref/migration-operations.txt b/docs/ref/migration-operations.txt
index a223ff6a23..b463bfc4ea 100644
--- a/docs/ref/migration-operations.txt
+++ b/docs/ref/migration-operations.txt
@@ -88,6 +88,17 @@ lose any data in the old table.
 Changes the model's table name (the :attr:`~django.db.models.Options.db_table`
 option on the ``Meta`` subclass).
 
+``AlterModelTableComment``
+--------------------------
+
+.. versionadded:: 4.2
+
+.. class:: AlterModelTableComment(name, table_comment)
+
+Changes the model's table comment (the
+:attr:`~django.db.models.Options.db_table_comment` option on the ``Meta``
+subclass).
+
 ``AlterUniqueTogether``
 -----------------------
 
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 0afddc14a8..d460e81ef4 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -325,6 +325,21 @@ characters that aren't allowed in Python variable names -- notably, the
 hyphen -- that's OK. Django quotes column and table names behind the
 scenes.
 
+``db_comment``
+--------------
+
+.. versionadded:: 4.2
+
+.. attribute:: Field.db_comment
+
+The comment on the database column to use for this field. It is useful for
+documenting fields for individuals with direct database access who may not be
+looking at your Django code. For example::
+
+    pub_date = models.DateTimeField(
+        db_comment="Date and time when the article was published",
+    )
+
 ``db_index``
 ------------
 
diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index a1629168af..a882fcb05a 100644
--- a/docs/ref/models/options.txt
+++ b/docs/ref/models/options.txt
@@ -91,6 +91,24 @@ Django quotes column and table names behind the scenes.
    backends; except for Oracle, however, the quotes have no effect. See the
    :ref:`Oracle notes <oracle-notes>` for more details.
 
+``db_table_comment``
+--------------------
+
+.. versionadded:: 4.2
+
+.. attribute:: Options.db_table_comment
+
+The comment on the database table to use for this model. It is useful for
+documenting database tables for individuals with direct database access who may
+not be looking at your Django code. For example::
+
+    class Answer(models.Model):
+        question = models.ForeignKey(Question, on_delete=models.CASCADE)
+        answer = models.TextField()
+
+        class Meta:
+            db_table_comment = "Question answers"
+
 ``db_tablespace``
 -----------------
 
diff --git a/docs/ref/schema-editor.txt b/docs/ref/schema-editor.txt
index 99d93f5ab4..fed3e76309 100644
--- a/docs/ref/schema-editor.txt
+++ b/docs/ref/schema-editor.txt
@@ -127,6 +127,15 @@ value.
 
 Renames the model's table from ``old_db_table`` to ``new_db_table``.
 
+``alter_db_table_comment()``
+----------------------------
+
+.. versionadded:: 4.2
+
+.. method:: BaseDatabaseSchemaEditor.alter_db_table_comment(model, old_db_table_comment, new_db_table_comment)
+
+Change the ``model``’s table comment to ``new_db_table_comment``.
+
 ``alter_db_tablespace()``
 -------------------------
 
diff --git a/docs/releases/4.2.txt b/docs/releases/4.2.txt
index 9710e889ca..90fdf9bd1b 100644
--- a/docs/releases/4.2.txt
+++ b/docs/releases/4.2.txt
@@ -40,6 +40,41 @@ in the future.
 .. _psycopg: https://www.psycopg.org/psycopg3/
 .. _psycopg library: https://pypi.org/project/psycopg/
 
+Comments on columns and tables
+------------------------------
+
+The new :attr:`Field.db_comment <django.db.models.Field.db_comment>` and
+:attr:`Meta.db_table_comment <django.db.models.Options.db_table_comment>`
+options allow creating comments on columns and tables, respectively. For
+example::
+
+    from django.db import models
+
+    class Question(models.Model):
+        text = models.TextField(db_comment="Poll question")
+        pub_date = models.DateTimeField(
+            db_comment="Date and time when the question was published",
+        )
+
+        class Meta:
+            db_table_comment = "Poll questions"
+
+
+    class Answer(models.Model):
+        question = models.ForeignKey(
+            Question,
+            on_delete=models.CASCADE,
+            db_comment="Reference to a question"
+        )
+        answer = models.TextField(db_comment="Question answer")
+
+        class Meta:
+            db_table_comment = "Question answers"
+
+Also, the new :class:`~django.db.migrations.operations.AlterModelTableComment`
+operation allows changing table comments defined in the
+:attr:`Meta.db_table_comment <django.db.models.Options.db_table_comment>`.
+
 Mitigation for the BREACH attack
 --------------------------------