feat(plugins): show table and column comments in sidebar and grid

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Per-tab database picker in the query editor toolbar. Each SQL tab can target its own database without clearing other tabs.
 - Single-clicking a table in the sidebar tree opens it in the current tab; double-clicking opens it in a new tab.
+- Table and column comments from the database now show in the UI. The sidebar shows a table's comment in dimmed text after its name, the data grid column header tooltip includes the column comment, and the table inspector shows the table comment. Toggle from View > Show Object Comments. Available for MySQL and PostgreSQL. (#1771)
 
 ### Changed
 

Plugins/MySQLDriverPlugin/MySQLPluginDriver.swift

@@ -188,13 +188,21 @@ final class MySQLPluginDriver: PluginDatabaseDriver, @unchecked Sendable {
     // MARK: - Schema Operations
 
     func fetchTables(schema: String?) async throws -> [PluginTableInfo] {
-        let result = try await execute(query: "SHOW FULL TABLES")
+        let query = """
+        SELECT TABLE_NAME, TABLE_TYPE, TABLE_COMMENT
+        FROM information_schema.TABLES
+        WHERE TABLE_SCHEMA = DATABASE()
+        """
+        let result = try await execute(query: query)
 
         return result.rows.compactMap { row -> PluginTableInfo? in
             guard let name = row[safe: 0]?.asText else { return nil }
             let typeStr = (row[safe: 1]?.asText) ?? "BASE TABLE"
-            let type = typeStr.contains("VIEW") ? "VIEW" : "TABLE"
-            return PluginTableInfo(name: name, type: type)
+            let isView = typeStr.contains("VIEW")
+            let type = isView ? "VIEW" : "TABLE"
+            let rawComment = row[safe: 2]?.asText
+            let comment = (!isView && rawComment?.isEmpty == false) ? rawComment : nil
+            return PluginTableInfo(name: name, type: type, comment: comment)
         }.sorted { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
     }
 

Plugins/PostgreSQLDriverPlugin/PostgreSQLPluginDriver.swift

@@ -182,7 +182,9 @@ final class PostgreSQLPluginDriver: LibPQBackedDriver, @unchecked Sendable {
             case "VIEW":              type = "VIEW"
             default:                  type = "TABLE"
             }
-            return PluginTableInfo(name: name, type: type)
+            let rawComment = row[safe: 2]?.asText
+            let comment = rawComment?.isEmpty == false ? rawComment : nil
+            return PluginTableInfo(name: name, type: type, comment: comment)
         }
     }
 

Plugins/PostgreSQLDriverPlugin/PostgreSQLSchemaQueries.swift

@@ -79,29 +79,37 @@ enum PostgreSQLSchemaQueries {
     ) -> String {
         var unions: [String] = [
             """
-            SELECT table_name, table_type FROM information_schema.tables
-            WHERE table_schema = '\(schemaLiteral)'
-              AND table_type IN ('BASE TABLE', 'VIEW')
+            SELECT t.table_name, t.table_type, d.description AS table_comment
+            FROM information_schema.tables t
+            LEFT JOIN pg_catalog.pg_namespace n ON n.nspname = t.table_schema
+            LEFT JOIN pg_catalog.pg_class c ON c.relname = t.table_name AND c.relnamespace = n.oid
+            LEFT JOIN pg_catalog.pg_description d ON d.objoid = c.oid AND d.objsubid = 0
+            WHERE t.table_schema = '\(schemaLiteral)'
+              AND t.table_type IN ('BASE TABLE', 'VIEW')
             """
         ]
 
         if includeMaterializedViews {
             unions.append(
                 """
-                SELECT matviewname AS table_name, 'MATERIALIZED VIEW' AS table_type
-                FROM pg_matviews
-                WHERE schemaname = '\(schemaLiteral)'
+                SELECT m.matviewname AS table_name, 'MATERIALIZED VIEW' AS table_type, d.description AS table_comment
+                FROM pg_matviews m
+                LEFT JOIN pg_catalog.pg_namespace n ON n.nspname = m.schemaname
+                LEFT JOIN pg_catalog.pg_class c ON c.relname = m.matviewname AND c.relnamespace = n.oid
+                LEFT JOIN pg_catalog.pg_description d ON d.objoid = c.oid AND d.objsubid = 0
+                WHERE m.schemaname = '\(schemaLiteral)'
                 """
             )
         }
 
         if includeForeignTables {
             unions.append(
                 """
-                SELECT c.relname AS table_name, 'FOREIGN TABLE' AS table_type
+                SELECT c.relname AS table_name, 'FOREIGN TABLE' AS table_type, d.description AS table_comment
                 FROM pg_foreign_table ft
                 JOIN pg_class c ON c.oid = ft.ftrelid
                 JOIN pg_namespace n ON n.oid = c.relnamespace
+                LEFT JOIN pg_catalog.pg_description d ON d.objoid = c.oid AND d.objsubid = 0
                 WHERE n.nspname = '\(schemaLiteral)'
                 """
             )

Plugins/TableProPluginKit/PluginTableInfo.swift

@@ -5,7 +5,23 @@ public struct PluginTableInfo: Codable, Sendable {
     public let type: String
     public let rowCount: Int?
     public let schema: String?
+    public let comment: String?
 
+    public init(
+        name: String,
+        type: String = "TABLE",
+        rowCount: Int? = nil,
+        schema: String? = nil,
+        comment: String?
+    ) {
+        self.name = name
+        self.type = type
+        self.rowCount = rowCount
+        self.schema = schema
+        self.comment = comment
+    }
+
+    @_disfavoredOverload
     public init(
         name: String,
         type: String = "TABLE",
@@ -16,5 +32,6 @@ public struct PluginTableInfo: Codable, Sendable {
         self.type = type
         self.rowCount = rowCount
         self.schema = schema
+        self.comment = nil
     }
 }

TablePro/Core/Coordinators/QueryExecutionCoordinator+Helpers.swift

@@ -79,6 +79,7 @@ extension QueryExecutionCoordinator {
         var columnDefaults: [String: String?] = [:]
         var columnForeignKeys: [String: ForeignKeyInfo] = [:]
         var columnNullable: [String: Bool] = [:]
+        var columnComments: [String: String] = [:]
         for (index, colType) in columnTypes.enumerated() {
             if case .enumType(_, let values) = colType, let vals = values, index < columns.count {
                 columnEnumValues[columns[index]] = vals
@@ -91,6 +92,7 @@ extension QueryExecutionCoordinator {
             columnDefaults = metadata.columnDefaults
             columnForeignKeys = metadata.columnForeignKeys ?? [:]
             columnNullable = metadata.columnNullable
+            columnComments = metadata.columnComments
             foreignKeysFetched = metadata.columnForeignKeys != nil
             for (col, vals) in metadata.columnEnumValues {
                 columnEnumValues[col] = vals
@@ -100,6 +102,7 @@ extension QueryExecutionCoordinator {
             columnDefaults = existing.columnDefaults
             columnForeignKeys = existing.columnForeignKeys
             columnNullable = existing.columnNullable
+            columnComments = existing.columnComments
             foreignKeysFetched = existing.foreignKeysFetched
             for (col, vals) in existing.columnEnumValues where columnEnumValues[col] == nil {
                 columnEnumValues[col] = vals
@@ -114,6 +117,7 @@ extension QueryExecutionCoordinator {
             columnForeignKeys: columnForeignKeys,
             columnEnumValues: columnEnumValues,
             columnNullable: columnNullable,
+            columnComments: columnComments,
             foreignKeysFetched: foreignKeysFetched
         )
         parent.setActiveTableRows(newTableRows, for: existingTabId)
@@ -333,7 +337,8 @@ extension QueryExecutionCoordinator {
             rows.updateDisplayMetadata(
                 columnDefaults: parsed.columnDefaults,
                 columnForeignKeys: parsed.columnForeignKeys,
-                columnNullable: parsed.columnNullable
+                columnNullable: parsed.columnNullable,
+                columnComments: parsed.columnComments
             )
         }
 

TablePro/Core/Plugins/PluginDriverAdapter.swift

@@ -194,7 +194,8 @@ final class PluginDriverAdapter: DatabaseDriver, SchemaSwitchable {
             name: table.name,
             type: tableType,
             rowCount: table.rowCount,
-            schema: table.schema ?? schemaFallback
+            schema: table.schema ?? schemaFallback,
+            comment: table.comment
         )
     }
 

TablePro/Core/Services/Query/QueryExecutor.swift

@@ -28,6 +28,7 @@ struct ParsedSchemaMetadata {
     let primaryKeyColumns: [String]
     let approximateRowCount: Int?
     let columnEnumValues: [String: [String]]
+    let columnComments: [String: String]
 }
 
 @MainActor
@@ -169,18 +170,23 @@ final class QueryExecutor {
             fks = byColumn
         }
         var enumValues: [String: [String]] = [:]
+        var comments: [String: String] = [:]
         for col in schema.columns {
             if let values = col.allowedValues, !values.isEmpty {
                 enumValues[col.name] = values
             }
+            if let comment = col.comment, !comment.isEmpty {
+                comments[col.name] = comment
+            }
         }
         return ParsedSchemaMetadata(
             columnDefaults: defaults,
             columnForeignKeys: fks,
             columnNullable: nullable,
             primaryKeyColumns: schema.columns.filter { $0.isPrimaryKey }.map(\.name),
             approximateRowCount: schema.approximateRowCount,
-            columnEnumValues: enumValues
+            columnEnumValues: enumValues,
+            columnComments: comments
         )
     }
 
@@ -200,7 +206,8 @@ final class QueryExecutor {
             columnNullable: nullable,
             primaryKeyColumns: primaryKeys,
             approximateRowCount: nil,
-            columnEnumValues: [:]
+            columnEnumValues: [:],
+            columnComments: [:]
         )
     }
 

TablePro/Models/Query/QueryResult.swift

@@ -91,6 +91,7 @@ struct TableInfo: Identifiable, Hashable, Sendable {
     let type: TableType
     let rowCount: Int?
     let schema: String?
+    let comment: String?
 
     enum TableType: String, Sendable {
         case table = "TABLE"
@@ -100,11 +101,12 @@ struct TableInfo: Identifiable, Hashable, Sendable {
         case systemTable = "SYSTEM TABLE"
     }
 
-    init(name: String, type: TableType, rowCount: Int?, schema: String? = nil) {
+    init(name: String, type: TableType, rowCount: Int?, schema: String? = nil, comment: String? = nil) {
         self.name = name
         self.type = type
         self.rowCount = rowCount
         self.schema = schema
+        self.comment = comment
     }
 
     static func == (lhs: TableInfo, rhs: TableInfo) -> Bool {

TablePro/Models/Query/TableRows.swift

@@ -15,6 +15,7 @@ struct TableRows: Sendable {
     var columnForeignKeys: [String: ForeignKeyInfo]
     var columnEnumValues: [String: [String]]
     var columnNullable: [String: Bool]
+    var columnComments: [String: String]
     var foreignKeysFetched: Bool
 
     init(
@@ -25,6 +26,7 @@ struct TableRows: Sendable {
         columnForeignKeys: [String: ForeignKeyInfo] = [:],
         columnEnumValues: [String: [String]] = [:],
         columnNullable: [String: Bool] = [:],
+        columnComments: [String: String] = [:],
         foreignKeysFetched: Bool = false
     ) {
         self.rows = rows
@@ -35,6 +37,7 @@ struct TableRows: Sendable {
         self.columnForeignKeys = columnForeignKeys
         self.columnEnumValues = columnEnumValues
         self.columnNullable = columnNullable
+        self.columnComments = columnComments
         self.foreignKeysFetched = foreignKeysFetched
     }
 
@@ -158,7 +161,8 @@ struct TableRows: Sendable {
         columnDefaults: [String: String?]? = nil,
         columnForeignKeys: [String: ForeignKeyInfo]? = nil,
         columnEnumValues: [String: [String]]? = nil,
-        columnNullable: [String: Bool]? = nil
+        columnNullable: [String: Bool]? = nil,
+        columnComments: [String: String]? = nil
     ) -> Delta {
         var didChange = false
         if let columnTypes, columnTypes != self.columnTypes {
@@ -184,6 +188,10 @@ struct TableRows: Sendable {
             self.columnNullable = columnNullable
             didChange = true
         }
+        if let columnComments, columnComments != self.columnComments {
+            self.columnComments = columnComments
+            didChange = true
+        }
         return didChange ? .columnsReplaced : .none
     }
 
@@ -195,6 +203,7 @@ struct TableRows: Sendable {
         columnForeignKeys: [String: ForeignKeyInfo] = [:],
         columnEnumValues: [String: [String]] = [:],
         columnNullable: [String: Bool] = [:],
+        columnComments: [String: String] = [:],
         foreignKeysFetched: Bool = false
     ) -> TableRows {
         var rows = ContiguousArray<Row>()
@@ -211,6 +220,7 @@ struct TableRows: Sendable {
             columnForeignKeys: columnForeignKeys,
             columnEnumValues: columnEnumValues,
             columnNullable: columnNullable,
+            columnComments: columnComments,
             foreignKeysFetched: foreignKeysFetched
         )
     }

TablePro/Models/Settings/GeneralSettings.swift

@@ -63,26 +63,32 @@ struct GeneralSettings: Codable, Equatable {
     /// Whether to share anonymous usage analytics
     var shareAnalytics: Bool
 
+    /// Whether to show database object comments in the sidebar and data grid headers
+    var showObjectComments: Bool
+
     static let `default` = GeneralSettings(
         startupBehavior: .reopenLast,
         language: .system,
         automaticallyCheckForUpdates: true,
         queryTimeoutSeconds: 60,
-        shareAnalytics: true
+        shareAnalytics: true,
+        showObjectComments: true
     )
 
     init(
         startupBehavior: StartupBehavior = .reopenLast,
         language: AppLanguage = .system,
         automaticallyCheckForUpdates: Bool = true,
         queryTimeoutSeconds: Int = 60,
-        shareAnalytics: Bool = true
+        shareAnalytics: Bool = true,
+        showObjectComments: Bool = true
     ) {
         self.startupBehavior = startupBehavior
         self.language = language
         self.automaticallyCheckForUpdates = automaticallyCheckForUpdates
         self.queryTimeoutSeconds = queryTimeoutSeconds
         self.shareAnalytics = shareAnalytics
+        self.showObjectComments = showObjectComments
     }
 
     init(from decoder: Decoder) throws {
@@ -92,5 +98,6 @@ struct GeneralSettings: Codable, Equatable {
         automaticallyCheckForUpdates = try container.decodeIfPresent(Bool.self, forKey: .automaticallyCheckForUpdates) ?? true
         queryTimeoutSeconds = try container.decodeIfPresent(Int.self, forKey: .queryTimeoutSeconds) ?? 60
         shareAnalytics = try container.decodeIfPresent(Bool.self, forKey: .shareAnalytics) ?? true
+        showObjectComments = try container.decodeIfPresent(Bool.self, forKey: .showObjectComments) ?? true
     }
 }

TablePro/TableProApp.swift

@@ -150,6 +150,13 @@ struct AppMenuCommands: Commands {
         )
     }
 
+    private var showObjectCommentsBinding: Binding<Bool> {
+        Binding(
+            get: { settingsManager.general.showObjectComments },
+            set: { settingsManager.general.showObjectComments = $0 }
+        )
+    }
+
     private func shortcut(for action: ShortcutAction) -> KeyboardShortcut? {
         settingsManager.keyboard.keyboardShortcut(for: action)
     }
@@ -603,6 +610,8 @@ struct AppMenuCommands: Commands {
             .pickerStyle(.inline)
             .disabled(!(actions?.canSwitchSidebarLayout ?? false))
 
+            Toggle(String(localized: "Show Object Comments"), isOn: showObjectCommentsBinding)
+
             Divider()
 
             Button("Toggle Filters") {