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, 26 insertions, 3 deletions

diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index a1d5a879d..e3bef8f82 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -2492,6 +2492,29 @@ class DDLCompiler(Compiled):
             self.process(create.element)
         )
 
+    def visit_set_table_comment(self, create):
+        return "COMMENT ON TABLE %s IS %s" % (
+            self.preparer.format_table(create.element),
+            self.sql_compiler.render_literal_value(
+                create.element.comment, sqltypes.String())
+        )
+
+    def visit_drop_table_comment(self, drop):
+        return "COMMENT ON TABLE %s IS NULL" % \
+            self.preparer.format_table(drop.element)
+
+    def visit_set_column_comment(self, create):
+        return "COMMENT ON COLUMN %s IS %s" % (
+            self.preparer.format_column(
+                create.element, use_table=True, use_schema=True),
+            self.sql_compiler.render_literal_value(
+                create.element.comment, sqltypes.String())
+        )
+
+    def visit_drop_column_comment(self, drop):
+        return "COMMENT ON COLUMN %s IS NULL" % \
+            self.preparer.format_column(drop.element, use_table=True)
+
     def visit_create_sequence(self, create):
         text = "CREATE SEQUENCE %s" % \
             self.preparer.format_sequence(create.element)
@@ -2996,7 +3019,7 @@ class IdentifierPreparer(object):
         return self.quote(name, quote)
 
     def format_column(self, column, use_table=False,
-                      name=None, table_name=None):
+                      name=None, table_name=None, use_schema=False):
         """Prepare a quoted column name."""
 
         if name is None:
@@ -3004,7 +3027,7 @@ class IdentifierPreparer(object):
         if not getattr(column, 'is_literal', False):
             if use_table:
                 return self.format_table(
-                    column.table, use_schema=False,
+                    column.table, use_schema=use_schema,
                     name=table_name) + "." + self.quote(name)
             else:
                 return self.quote(name)
@@ -3014,7 +3037,7 @@ class IdentifierPreparer(object):
 
             if use_table:
                 return self.format_table(
-                    column.table, use_schema=False,
+                    column.table, use_schema=use_schema,
                     name=table_name) + '.' + name
             else:
                 return name