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

2 files changed, 48 insertions, 2 deletions

diff --git a/lib/sqlalchemy/testing/requirements.py b/lib/sqlalchemy/testing/requirements.py
index e4491ca7c..d38a69159 100644
--- a/lib/sqlalchemy/testing/requirements.py
+++ b/lib/sqlalchemy/testing/requirements.py
@@ -322,6 +322,10 @@ class SuiteRequirements(Requirements):
         return exclusions.open()
 
     @property
+    def comment_reflection(self):
+        return exclusions.closed()
+
+    @property
     def view_column_reflection(self):
         """target database must support retrieval of the columns in a view,
         similarly to how a table is inspected.
diff --git a/lib/sqlalchemy/testing/suite/test_reflection.py b/lib/sqlalchemy/testing/suite/test_reflection.py
index 572cc4a0a..a761c0882 100644
--- a/lib/sqlalchemy/testing/suite/test_reflection.py
+++ b/lib/sqlalchemy/testing/suite/test_reflection.py
@@ -102,6 +102,11 @@ class ComponentReflectionTest(fixtures.TablesTest):
               schema=schema,
               test_needs_fk=True,
               )
+        Table('comment_test', metadata,
+              Column('id', sa.Integer, primary_key=True, comment='id comment'),
+              Column('data', sa.String(20), comment='data comment'),
+              schema=schema,
+              comment='the test table comment')
 
         if testing.requires.index_reflection.enabled:
             cls.define_index(metadata, users)
@@ -203,8 +208,11 @@ class ComponentReflectionTest(fixtures.TablesTest):
             answer = ['email_addresses_v', 'users_v']
             eq_(sorted(table_names), answer)
         else:
-            table_names = insp.get_table_names(schema,
-                                               order_by=order_by)
+            table_names = [
+                t for t in insp.get_table_names(
+                    schema,
+                    order_by=order_by) if t not in ('comment_test', )]
+
             if order_by == 'foreign_key':
                 answer = ['users', 'email_addresses', 'dingalings']
                 eq_(table_names, answer)
@@ -235,6 +243,40 @@ class ComponentReflectionTest(fixtures.TablesTest):
     def test_get_table_names_fks(self):
         self._test_get_table_names(order_by='foreign_key')
 
+    @testing.requires.comment_reflection
+    def test_get_comments(self):
+        self._test_get_comments()
+
+    @testing.requires.comment_reflection
+    @testing.requires.schemas
+    def test_get_comments_with_schema(self):
+        self._test_get_comments(testing.config.test_schema)
+
+    def _test_get_comments(self, schema=None):
+        insp = inspect(testing.db)
+
+        eq_(
+            insp.get_table_comment("comment_test", schema=schema),
+            {"text": "the test table comment"}
+        )
+
+        eq_(
+            insp.get_table_comment("users", schema=schema),
+            {"text": None}
+        )
+
+        eq_(
+            [
+                {"name": rec['name'], "comment": rec['comment']}
+                for rec in
+                insp.get_columns("comment_test", schema=schema)
+            ],
+            [
+                {'comment': 'id comment', 'name': 'id'},
+                {'comment': 'data comment', 'name': 'data'}
+            ]
+        )
+
     @testing.requires.table_reflection
     @testing.requires.schemas
     def test_get_table_names_with_schema(self):