sql: add schema descriptions as table and column comments

The steampipe CLI does this, and it's very helpful when trying to figure
out what a specific table or column holds.

Author: isaac-sec

schema.go

@@ -65,8 +65,10 @@ func SchemaToSql(schema map[string]*proto.TableSchema, stmt *C.ImportForeignSche
 			return nil
 		}
 
-		log.Printf("[TRACE] SQL %s", sql)
-		commands = C.lappend(commands, unsafe.Pointer(C.CString(sql)))
+		for _, s := range sql {
+			log.Printf("[TRACE] SQL %s", s)
+			commands = C.lappend(commands, unsafe.Pointer(C.CString(s)))
+		}
 	}
 
 	return commands

sql/sql.go

@@ -8,27 +8,38 @@ import (
 	"github.com/turbot/steampipe/pkg/db/db_common"
 )
 
-func GetSQLForTable(table string, tableSchema *proto.TableSchema, localSchema string, serverName string) (string, error) {
+func GetSQLForTable(table string, tableSchema *proto.TableSchema, localSchema string, serverName string) ([]string, error) {
 	// escape everything
 	serverName = db_common.PgEscapeName(serverName)
 	localSchema = db_common.PgEscapeName(localSchema)
 	escapedTableName := db_common.PgEscapeName(table)
 	// we must escape differently for the option
 	escapedTableString := db_common.PgEscapeString(table)
 
+	var commentStatements []string
+	if tableSchema.Description != "" {
+		tableDescription := db_common.PgEscapeString(tableSchema.Description)
+		commentStatements = append(commentStatements, fmt.Sprintf("COMMENT ON FOREIGN TABLE %s.%s IS %s", localSchema, escapedTableName, tableDescription))
+	}
+
 	var columnsString []string
 	for i, c := range tableSchema.Columns {
 		column := db_common.PgEscapeName(c.Name)
 		t, err := sqlTypeForColumnType(c.Type)
 		if err != nil {
-			return "", err
+			return nil, err
 		}
 		trailing := ","
 		if i+1 == len(tableSchema.Columns) {
 			trailing = ""
 		}
 
 		columnsString = append(columnsString, fmt.Sprintf("%s %s%s", column, t, trailing))
+
+		if c.Description != "" {
+			columnDescription := db_common.PgEscapeString(c.Description)
+			commentStatements = append(commentStatements, fmt.Sprintf("COMMENT ON COLUMN %s.%s.%s IS %s", localSchema, escapedTableName, column, columnDescription))
+		}
 	}
 
 	sql := fmt.Sprintf(`CREATE FOREIGN TABLE IF NOT EXISTS %s.%s
@@ -42,7 +53,7 @@ SERVER %s OPTIONS (table %s)`,
 		serverName,
 		escapedTableString)
 
-	return sql, nil
+	return append([]string{sql}, commentStatements...), nil
 }
 
 func sqlTypeForColumnType(columnType proto.ColumnType) (string, error) {

sql/sql_test.go

@@ -1,6 +1,7 @@
 package sql
 
 import (
+	"slices"
 	"testing"
 
 	"github.com/turbot/steampipe-plugin-sdk/v5/grpc/proto"
@@ -11,7 +12,7 @@ type getSQLForTableTest struct {
 	tableSchema *proto.TableSchema
 	localSchema string
 	serverName  string
-	expected    string
+	expected    []string
 }
 
 var testCasesgetSQLForTable = map[string]getSQLForTableTest{
@@ -31,12 +32,14 @@ var testCasesgetSQLForTable = map[string]getSQLForTableTest{
 		},
 		localSchema: "aws",
 		serverName:  "steampipe",
-		expected: `create foreign table "aws"."t1"
+		expected: []string{
+			`CREATE FOREIGN TABLE IF NOT EXISTS "aws"."t1"
 (
-  "c1" text,
+  "c1" text
   "c2" text
 )
-server "steampipe" OPTIONS (table $steampipe_escape$t1$steampipe_escape$)`},
+SERVER "steampipe" OPTIONS (table $steampipe_escape$t1$steampipe_escape$)`,
+		}},
 	"quotes in names": {
 		table: "t1",
 		tableSchema: &proto.TableSchema{
@@ -53,27 +56,29 @@ server "steampipe" OPTIONS (table $steampipe_escape$t1$steampipe_escape$)`},
 		},
 		localSchema: "aws",
 		serverName:  "steampipe",
-		expected: `create foreign table "aws"."t1"
+		expected: []string{
+			`CREATE FOREIGN TABLE IF NOT EXISTS "aws"."t1"
 (
-  """c1""" text,
+  """c1""" text
   "c2 ""is"" partially quoted" text
 )
-server "steampipe" OPTIONS (table $steampipe_escape$t1$steampipe_escape$)`},
+SERVER "steampipe" OPTIONS (table $steampipe_escape$t1$steampipe_escape$)`,
+		}},
 }
 
 func TestGetSQLForTable(t *testing.T) {
 	for name, test := range testCasesgetSQLForTable {
 
 		result, err := GetSQLForTable(test.table, test.tableSchema, test.localSchema, test.serverName)
 		if err != nil {
-			if test.expected != "ERROR" {
+			if test.expected != nil {
 				t.Errorf(`Test: '%s'' FAILED : unexpected error %v`, name, err)
 			}
 			continue
 		}
 
-		if test.expected != result {
-			t.Errorf("Test: '%s' FAILED : expected \n%s\ngot\n%s", name, test.expected, result)
+		if !slices.Equal(test.expected, result) {
+			t.Errorf("Test: '%s' FAILED : expected \n%v\ngot\n%v", name, test.expected, result)
 		}
 	}
 }