Implement comments for tables, columns

Added support for SQL comments on :class:`.Table` and :class:`.Column`
objects, via the new :paramref:`.Table.comment` and
:paramref:`.Column.comment` arguments.   The comments are included
as part of DDL on table creation, either inline or via an appropriate
ALTER statement, and are also reflected back within table reflection,
as well as via the :class:`.Inspector`.   Supported backends currently
include MySQL, Postgresql, and Oracle.

Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com>
Fixes: #1546
Change-Id: Ib90683850805a2b4ee198e420dc294f32f15d35d

1 files changed, 22 insertions, 2 deletions

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index e6eabc461..accc1fe0d 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -371,6 +371,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
 
     :param useexisting: Deprecated.  Use :paramref:`.Table.extend_existing`.
 
+    :param comment: Optional string that will render an SQL comment on table
+         creation.
+
+         .. versionadded:: 1.2 Added the :paramref:`.Table.comment` parameter
+            to :class:`.Table`.
+
     :param \**kw: Additional keyword arguments not mentioned above are
         dialect specific, and passed in the form ``<dialectname>_<argname>``.
         See the documentation regarding an individual dialect at
@@ -494,6 +500,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
 
         self.implicit_returning = kwargs.pop('implicit_returning', True)
 
+        self.comment = kwargs.pop('comment', None)
+
         if 'info' in kwargs:
             self.info = kwargs.pop('info')
         if 'listeners' in kwargs:
@@ -588,6 +596,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         if 'info' in kwargs:
             self.info = kwargs.pop('info')
 
+        self.comment = kwargs.pop('comment', None)
+
         if autoload:
             if not autoload_replace:
                 # don't replace columns already present.
@@ -1044,8 +1054,9 @@ class Column(SchemaItem, ColumnClause):
                 :ref:`metadata_defaults_toplevel`
 
         :param doc: optional String that can be used by the ORM or similar
-            to document attributes.   This attribute does not render SQL
-            comments (a future attribute 'comment' will achieve that).
+            to document attributes on the Python side.   This attribute does
+            **not** render SQL comments; use the :paramref:`.Column.comment`
+            parameter for this purpose.
 
         :param key: An optional string identifier which will identify this
             ``Column`` object on the :class:`.Table`. When a key is provided,
@@ -1159,6 +1170,13 @@ class Column(SchemaItem, ColumnClause):
              .. versionadded:: 0.8.3 Added the ``system=True`` parameter to
                 :class:`.Column`.
 
+        :param comment: Optional string that will render an SQL comment on
+             table creation.
+
+             .. versionadded:: 1.2 Added the :paramref:`.Column.comment`
+                parameter to :class:`.Column`.
+
+
         """
 
         name = kwargs.pop('name', None)
@@ -1205,6 +1223,7 @@ class Column(SchemaItem, ColumnClause):
         self.autoincrement = kwargs.pop('autoincrement', "auto")
         self.constraints = set()
         self.foreign_keys = set()
+        self.comment = kwargs.pop('comment', None)
 
         # check if this Column is proxying another column
         if '_proxies' in kwargs:
@@ -2309,6 +2328,7 @@ class Sequence(DefaultGenerator):
             % self.__class__.__name__)
 
 
+
 @inspection._self_inspects
 class FetchedValue(_NotAColumnExpr, SchemaEventTarget):
     """A marker for a transparent database-side default.