feat(dbml): support case-insensitive table note parsing

* Add parsing for triple-quoted table notes in DBML
* Update writer to format multiline notes correctly
* Enhance tests for multiline table notes handling

cmd/relspec/diff.go

@@ -229,43 +229,43 @@ func readDatabase(dbType, filePath, connString, label string) (*models.Database,
 		if filePath == "" {
 			return nil, fmt.Errorf("%s: file path is required for DBML format", label)
 		}
-		reader = dbml.NewReader(&readers.ReaderOptions{FilePath: filePath})
+		reader = dbml.NewReader(newReaderOptions(filePath, ""))
 
 	case "dctx":
 		if filePath == "" {
 			return nil, fmt.Errorf("%s: file path is required for DCTX format", label)
 		}
-		reader = dctx.NewReader(&readers.ReaderOptions{FilePath: filePath})
+		reader = dctx.NewReader(newReaderOptions(filePath, ""))
 
 	case "drawdb":
 		if filePath == "" {
 			return nil, fmt.Errorf("%s: file path is required for DrawDB format", label)
 		}
-		reader = drawdb.NewReader(&readers.ReaderOptions{FilePath: filePath})
+		reader = drawdb.NewReader(newReaderOptions(filePath, ""))
 
 	case "json":
 		if filePath == "" {
 			return nil, fmt.Errorf("%s: file path is required for JSON format", label)
 		}
-		reader = json.NewReader(&readers.ReaderOptions{FilePath: filePath})
+		reader = json.NewReader(newReaderOptions(filePath, ""))
 
 	case "yaml":
 		if filePath == "" {
 			return nil, fmt.Errorf("%s: file path is required for YAML format", label)
 		}
-		reader = yaml.NewReader(&readers.ReaderOptions{FilePath: filePath})
+		reader = yaml.NewReader(newReaderOptions(filePath, ""))
 
 	case "sqldir", "scripts", "scriptdir":
 		if filePath == "" {
 			return nil, fmt.Errorf("%s: file path is required for SQL directory format", label)
 		}
-		reader = sqldir.NewReader(&readers.ReaderOptions{FilePath: filePath})
+		reader = sqldir.NewReader(newReaderOptions(filePath, ""))
 
 	case "pgsql", "postgres", "postgresql":
 		if connString == "" {
 			return nil, fmt.Errorf("%s: connection string is required for PostgreSQL format", label)
 		}
-		reader = pgsql.NewReader(&readers.ReaderOptions{ConnectionString: connString})
+		reader = pgsql.NewReader(newReaderOptions("", connString))
 
 	case "sqlite", "sqlite3":
 		// SQLite can use either file path or connection string
@@ -276,7 +276,7 @@ func readDatabase(dbType, filePath, connString, label string) (*models.Database,
 		if dbPath == "" {
 			return nil, fmt.Errorf("%s: file path or connection string is required for SQLite format", label)
 		}
-		reader = sqlite.NewReader(&readers.ReaderOptions{FilePath: dbPath})
+		reader = sqlite.NewReader(newReaderOptions(dbPath, ""))
 
 	default:
 		return nil, fmt.Errorf("%s: unsupported database format: %s", label, dbType)

cmd/relspec/main.go

@@ -6,9 +6,40 @@ import (
 )
 
 func main() {
-	printVersionHeader(os.Args[1:])
+	args := os.Args[1:]
-	if err := rootCmd.Execute(); err != nil {
+	isSilent := hasSilentFlag(args)
+	if !isSilent {
+		printVersionHeader(args)
+	}
+
+	previousStderr := os.Stderr
+	var nullOutput *os.File
+	if isSilent {
+		var err error
+		nullOutput, err = os.OpenFile(os.DevNull, os.O_WRONLY, 0)
+		if err != nil {
+			fmt.Fprintln(previousStderr, err)
+			os.Exit(1)
+		}
+		os.Stderr = nullOutput
+	}
+
+	err := rootCmd.Execute()
+	if nullOutput != nil {
+		os.Stderr = previousStderr
+		nullOutput.Close()
+	}
+	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
 	}
 }
+
+func hasSilentFlag(args []string) bool {
+	for _, arg := range args {
+		if arg == "--silent" || arg == "--silent=true" {
+			return true
+		}
+	}
+	return false
+}

cmd/relspec/merge.go

@@ -178,7 +178,7 @@ func runMerge(cmd *cobra.Command, args []string) error {
 	}
 
 	// Step 1: Read target database
-	fmt.Fprintf(os.Stderr, "[1/3] Reading target database...\n")
+	fmt.Fprintf(os.Stderr, "[1/4] Reading target database...\n")
 	fmt.Fprintf(os.Stderr, "      Format: %s\n", mergeTargetType)
 	if mergeTargetPath != "" {
 		fmt.Fprintf(os.Stderr, "      Path:   %s\n", mergeTargetPath)
@@ -195,7 +195,7 @@ func runMerge(cmd *cobra.Command, args []string) error {
 	printDatabaseStats(targetDB)
 
 	// Step 2: Read source database(s)
-	fmt.Fprintf(os.Stderr, "\n[2/3] Reading source database...\n")
+	fmt.Fprintf(os.Stderr, "\n[2/4] Reading source database...\n")
 	fmt.Fprintf(os.Stderr, "      Format: %s\n", mergeSourceType)
 
 	var sourceDB *models.Database
@@ -229,7 +229,7 @@ func runMerge(cmd *cobra.Command, args []string) error {
 	printDatabaseStats(sourceDB)
 
 	// Step 3: Merge databases
-	fmt.Fprintf(os.Stderr, "\n[3/3] Merging databases...\n")
+	fmt.Fprintf(os.Stderr, "\n[3/4] Merging databases...\n")
 
 	opts := &merge.MergeOptions{
 		SkipDomains:   mergeSkipDomains,
@@ -267,6 +267,9 @@ func runMerge(cmd *cobra.Command, args []string) error {
 	if mergeOutputPath != "" {
 		fmt.Fprintf(os.Stderr, "      Path:   %s\n", mergeOutputPath)
 	}
+	if mergeOutputConn != "" {
+		fmt.Fprintf(os.Stderr, "      Conn:   %s\n", maskPassword(mergeOutputConn))
+	}
 
 	err = writeDatabaseForMerge(mergeOutputType, mergeOutputPath, mergeOutputConn, targetDB, "Output", mergeFlattenSchema)
 	if err != nil {

cmd/relspec/prisma_options.go

@@ -1,6 +1,9 @@
 package main
 
 import (
+	"fmt"
+	"os"
+
 	"git.warky.dev/wdevs/relspecgo/pkg/readers"
 	"git.warky.dev/wdevs/relspecgo/pkg/writers"
 )
@@ -11,6 +14,9 @@ func newReaderOptions(filePath, connString string) *readers.ReaderOptions {
 		ConnectionString: connString,
 		Prisma7:          prisma7,
 		StrictDirectives: strictDirectives,
+		Progress: func(message string) {
+			fmt.Fprintf(os.Stderr, "      → %s\n", message)
+		},
 	}
 }
 

cmd/relspec/root.go

@@ -14,6 +14,7 @@ var (
 	buildDate        = "unknown"
 	prisma7          bool
 	noVersion        bool
+	silent           bool
 	strictDirectives bool
 )
 
@@ -73,6 +74,7 @@ func init() {
 	rootCmd.AddCommand(reportCmd)
 	rootCmd.PersistentFlags().BoolVar(&prisma7, "prisma7", false, "Use Prisma 7 generator conventions when reading/writing Prisma schemas")
 	rootCmd.PersistentFlags().BoolVar(&noVersion, "no-version", false, "Suppress the RelSpec version header")
+	rootCmd.PersistentFlags().BoolVar(&silent, "silent", false, "Suppress progress and status messages (errors are still shown)")
 	rootCmd.PersistentFlags().BoolVar(&strictDirectives, "strict-directives", false, "Fail on unknown or untranslatable DBML dialect directives (@postgres:, @sqlite:, …)")
 }
 

pkg/readers/dbml/reader.go

@@ -434,6 +434,9 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 	var currentSchema string
 	var inIndexes bool
 	var inTable bool
+	var inTableNote bool
+	var tableNoteLines []string
+	tableNoteStartLine := 0
 	var columnSeq uint
 	var lastIndex *models.Index // most recent index in the current Indexes block
 	lineNo := 0
@@ -443,7 +446,22 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 
 	for scanner.Scan() {
 		lineNo++
-		line := strings.TrimSpace(scanner.Text())
+		rawLine := scanner.Text()
+		line := strings.TrimSpace(rawLine)
+
+		// A table note can use DBML's triple-quoted form. Its contents must be
+		// consumed before normal parsing, otherwise each prose line is mistaken
+		// for a column declaration.
+		if inTableNote {
+			if line == "'''" {
+				setTableNote(currentTable, strings.TrimSpace(strings.Join(tableNoteLines, "\n")))
+				inTableNote = false
+				tableNoteLines = nil
+				continue
+			}
+			tableNoteLines = append(tableNoteLines, strings.TrimSpace(rawLine))
+			continue
+		}
 
 		// Skip empty lines and comments
 		if line == "" || strings.HasPrefix(line, "//") {
@@ -539,11 +557,18 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 			continue
 		}
 
-		// Parse table note
+		// Parse table note. DBML files in the wild use both `Note:` and
-		if inTable && currentTable != nil && strings.HasPrefix(line, "Note:") {
+		// `note:`, so accept either spelling.
-			note := strings.TrimPrefix(line, "Note:")
+		if inTable && currentTable != nil && strings.HasPrefix(strings.ToLower(line), "note:") {
+			note := strings.TrimSpace(line[len("note:"):])
+			if strings.TrimSpace(note) == "'''" {
+				inTableNote = true
+				tableNoteLines = nil
+				tableNoteStartLine = lineNo
+				continue
+			}
 			note = strings.Trim(note, " '\"")
-			currentTable.Description = note
+			setTableNote(currentTable, note)
 			continue
 		}
 
@@ -580,6 +605,13 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 		}
 	}
 
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("failed to scan DBML: %w", err)
+	}
+	if inTableNote {
+		return nil, fmt.Errorf("dbml: line %d: unterminated triple-quoted table note", tableNoteStartLine)
+	}
+
 	// Assign pending constraints to their respective tables
 	for _, constraint := range pendingConstraints {
 		// Find the table this constraint belongs to
@@ -623,6 +655,20 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 	return db, nil
 }
 
+// setTableNote preserves multiple table notes. The first maps to Description
+// and the second to Comment, matching the model fields used by code writers.
+func setTableNote(table *models.Table, note string) {
+	if table.Description == "" {
+		table.Description = note
+		return
+	}
+	if table.Comment == "" {
+		table.Comment = note
+		return
+	}
+	table.Comment += "\n" + note
+}
+
 // parseColumn parses a DBML column definition
 func (r *Reader) parseColumn(line, tableName, schemaName string) (*models.Column, *models.Constraint) {
 	// Format: column_name type [attributes] // comment
@@ -640,7 +686,7 @@ func (r *Reader) parseColumn(line, tableName, schemaName string) (*models.Column
 
 	// Parse attributes in brackets
 	if attrs != "" {
-		attrList := strings.Split(attrs, ",")
+		attrList := splitColumnAttrs(attrs)
 
 		for _, attr := range attrList {
 			attr = strings.TrimSpace(attr)
@@ -723,6 +769,44 @@ func (r *Reader) parseColumn(line, tableName, schemaName string) (*models.Column
 	return column, constraint
 }
 
+// splitColumnAttrs splits a DBML attribute list on top-level commas. Notes and
+// quoted defaults may contain commas of their own, which are part of the value
+// rather than attribute separators.
+func splitColumnAttrs(attrs string) []string {
+	var result []string
+	start := 0
+	var quote byte
+	escaped := false
+
+	for i := 0; i < len(attrs); i++ {
+		ch := attrs[i]
+		if quote != 0 {
+			if escaped {
+				escaped = false
+				continue
+			}
+			if ch == '\\' {
+				escaped = true
+				continue
+			}
+			if ch == quote {
+				quote = 0
+			}
+			continue
+		}
+
+		switch ch {
+		case '\'', '"', '`':
+			quote = ch
+		case ',':
+			result = append(result, attrs[start:i])
+			start = i + 1
+		}
+	}
+
+	return append(result, attrs[start:])
+}
+
 func splitInlineComment(line string) (content, inlineComment string) {
 	commentStart := strings.Index(line, "//")
 	if commentStart == -1 {

pkg/readers/dbml/reader_test.go

@@ -1033,3 +1033,39 @@ func TestReader_ColumnPKOrderPreserved(t *testing.T) {
 		t.Errorf("expected snapshot_id (declared first) to have a lower Sequence than artifact_id, got %d >= %d", snapshotCol.Sequence, artifactCol.Sequence)
 	}
 }
+
+func TestReader_MultilineTableNote(t *testing.T) {
+	dbmlContent := "Table \"info\".\"city\" {\n" +
+		"  \"id_city\" serial [pk, not null, increment]\n" +
+		"  \"name\" text [not null, note: 'first, second, third']\n\n" +
+		"  note: '''\n" +
+		"  Cities and municipalities worldwide.\n\n" +
+		"  SPATIAL:\n" +
+		"  Proximity queries use a GiST index.\n" +
+		"  '''\n" +
+		"  Note: 'Short summary'\n" +
+		"}\n"
+	path := filepath.Join(t.TempDir(), "city.dbml")
+	if err := os.WriteFile(path, []byte(dbmlContent), 0o644); err != nil {
+		t.Fatalf("failed to write fixture: %v", err)
+	}
+
+	db, err := NewReader(&readers.ReaderOptions{FilePath: path}).ReadDatabase()
+	if err != nil {
+		t.Fatalf("ReadDatabase() error = %v", err)
+	}
+
+	table := db.Schemas[0].Tables[0]
+	if got, want := table.Description, "Cities and municipalities worldwide.\n\nSPATIAL:\nProximity queries use a GiST index."; got != want {
+		t.Errorf("table description = %q, want %q", got, want)
+	}
+	if got, want := table.Comment, "Short summary"; got != want {
+		t.Errorf("table comment = %q, want %q", got, want)
+	}
+	if got, want := len(table.Columns), 2; got != want {
+		t.Errorf("column count = %d, want %d; note body must not be parsed as columns", got, want)
+	}
+	if got, want := table.Columns["name"].Comment, "first, second, third"; got != want {
+		t.Errorf("column note = %q, want %q", got, want)
+	}
+}

pkg/readers/pgsql/reader.go

@@ -34,11 +34,14 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 		return nil, fmt.Errorf("connection string is required")
 	}
 
-	// Connect to the database
+	// Connect to the database. This can take noticeable time across a slow network,
+	// so report it before the driver starts the connection attempt.
+	r.progress("Connecting to PostgreSQL...")
 	if err := r.connect(); err != nil {
 		return nil, fmt.Errorf("failed to connect: %w", err)
 	}
 	defer r.close()
+	r.progress("Connected. Reading database metadata...")
 
 	// Get database name from connection
 	var dbName string
@@ -60,34 +63,42 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 	}
 
 	// Query all schemas
+	r.progress("Discovering schemas...")
 	schemas, err := r.querySchemas()
 	if err != nil {
 		return nil, fmt.Errorf("failed to query schemas: %w", err)
 	}
 
 	// Process each schema
-	for _, schema := range schemas {
+	for schemaIndex, schema := range schemas {
+		r.progress(fmt.Sprintf("Reading schema %q (%d/%d): tables...", schema.Name, schemaIndex+1, len(schemas)))
 		// Query tables for this schema
 		tables, err := r.queryTables(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query tables for schema %s: %w", schema.Name, err)
 		}
 		schema.Tables = tables
+		r.progress(fmt.Sprintf("Reading schema %q: found %d table(s).", schema.Name, len(tables)))
 
+		r.progress(fmt.Sprintf("Reading schema %q: views...", schema.Name))
 		// Query views for this schema
 		views, err := r.queryViews(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query views for schema %s: %w", schema.Name, err)
 		}
 		schema.Views = views
+		r.progress(fmt.Sprintf("Reading schema %q: found %d view(s).", schema.Name, len(views)))
 
+		r.progress(fmt.Sprintf("Reading schema %q: sequences...", schema.Name))
 		// Query sequences for this schema
 		sequences, err := r.querySequences(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query sequences for schema %s: %w", schema.Name, err)
 		}
 		schema.Sequences = sequences
+		r.progress(fmt.Sprintf("Reading schema %q: found %d sequence(s).", schema.Name, len(sequences)))
 
+		r.progress(fmt.Sprintf("Reading schema %q: extensions...", schema.Name))
 		// Query extensions installed into this schema
 		extensions, err := r.queryExtensions(schema.Name)
 		if err != nil {
@@ -99,12 +110,15 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 			}
 			schema.Metadata["extensions"] = extensions
 		}
+		r.progress(fmt.Sprintf("Reading schema %q: found %d extension(s).", schema.Name, len(extensions)))
 
+		r.progress(fmt.Sprintf("Reading schema %q: columns...", schema.Name))
 		// Query columns for tables and views
 		columnsMap, err := r.queryColumns(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query columns for schema %s: %w", schema.Name, err)
 		}
+		r.progress(fmt.Sprintf("Reading schema %q: found %d column(s).", schema.Name, countColumns(columnsMap)))
 
 		// Populate table columns
 		for _, table := range schema.Tables {
@@ -122,11 +136,13 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 			}
 		}
 
+		r.progress(fmt.Sprintf("Reading schema %q: primary keys...", schema.Name))
 		// Query primary keys
 		primaryKeys, err := r.queryPrimaryKeys(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query primary keys for schema %s: %w", schema.Name, err)
 		}
+		r.progress(fmt.Sprintf("Reading schema %q: found %d primary key(s).", schema.Name, len(primaryKeys)))
 
 		// Apply primary keys to tables
 		for _, table := range schema.Tables {
@@ -143,11 +159,13 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 			}
 		}
 
+		r.progress(fmt.Sprintf("Reading schema %q: foreign keys...", schema.Name))
 		// Query foreign keys
 		foreignKeys, err := r.queryForeignKeys(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query foreign keys for schema %s: %w", schema.Name, err)
 		}
+		r.progress(fmt.Sprintf("Reading schema %q: found %d foreign key(s).", schema.Name, countConstraints(foreignKeys)))
 
 		// Apply foreign keys to tables
 		for _, table := range schema.Tables {
@@ -161,11 +179,13 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 			}
 		}
 
+		r.progress(fmt.Sprintf("Reading schema %q: unique constraints...", schema.Name))
 		// Query unique constraints
 		uniqueConstraints, err := r.queryUniqueConstraints(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query unique constraints for schema %s: %w", schema.Name, err)
 		}
+		r.progress(fmt.Sprintf("Reading schema %q: found %d unique constraint(s).", schema.Name, countConstraints(uniqueConstraints)))
 
 		// Apply unique constraints to tables
 		for _, table := range schema.Tables {
@@ -177,11 +197,13 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 			}
 		}
 
+		r.progress(fmt.Sprintf("Reading schema %q: check constraints...", schema.Name))
 		// Query check constraints
 		checkConstraints, err := r.queryCheckConstraints(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query check constraints for schema %s: %w", schema.Name, err)
 		}
+		r.progress(fmt.Sprintf("Reading schema %q: found %d check constraint(s).", schema.Name, countConstraints(checkConstraints)))
 
 		// Apply check constraints to tables
 		for _, table := range schema.Tables {
@@ -193,11 +215,13 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 			}
 		}
 
+		r.progress(fmt.Sprintf("Reading schema %q: indexes...", schema.Name))
 		// Query indexes
 		indexes, err := r.queryIndexes(schema.Name)
 		if err != nil {
 			return nil, fmt.Errorf("failed to query indexes for schema %s: %w", schema.Name, err)
 		}
+		r.progress(fmt.Sprintf("Reading schema %q: found %d index(es).", schema.Name, countIndexes(indexes)))
 
 		// Apply indexes to tables
 		for _, table := range schema.Tables {
@@ -226,10 +250,41 @@ func (r *Reader) ReadDatabase() (*models.Database, error) {
 		// Add schema to database
 		db.Schemas = append(db.Schemas, schema)
 	}
+	r.progress("PostgreSQL schema read complete.")
 
 	return db, nil
 }
 
+func (r *Reader) progress(message string) {
+	if r.options.Progress != nil {
+		r.options.Progress(message)
+	}
+}
+
+func countColumns(columns map[string]map[string]*models.Column) int {
+	total := 0
+	for _, tableColumns := range columns {
+		total += len(tableColumns)
+	}
+	return total
+}
+
+func countConstraints(constraints map[string][]*models.Constraint) int {
+	total := 0
+	for _, tableConstraints := range constraints {
+		total += len(tableConstraints)
+	}
+	return total
+}
+
+func countIndexes(indexes map[string][]*models.Index) int {
+	total := 0
+	for _, tableIndexes := range indexes {
+		total += len(tableIndexes)
+	}
+	return total
+}
+
 // ReadSchema reads a single schema (returns the first schema from the database)
 func (r *Reader) ReadSchema() (*models.Schema, error) {
 	db, err := r.ReadDatabase()

pkg/readers/reader.go

@@ -32,6 +32,10 @@ type ReaderOptions struct {
 	// fail on an unknown namespace or key instead of preserving them silently.
 	StrictDirectives bool
 
+	// Progress receives human-readable status updates while a reader is working.
+	// It is optional so library users can opt in without coupling readers to a UI.
+	Progress func(string)
+
 	// Additional options can be added here as needed
 	Metadata map[string]interface{}
 }

pkg/writers/bun/template_data.go

@@ -279,13 +279,16 @@ func (md *ModelData) AddRelationshipField(field *FieldData) {
 
 // formatComment combines description and comment into a single comment string
 func formatComment(description, comment string) string {
+	var result string
 	if description != "" && comment != "" {
-		return description + " - " + comment
+		result = description + " - " + comment
+	} else if description != "" {
+		result = description
+	} else {
+		result = comment
 	}
-	if description != "" {
+	// Generated Go comments are emitted on a single source line.
-		return description
+	return strings.Join(strings.Fields(result), " ")
-	}
-	return comment
 }
 
 func isStringLikePrimaryKeyType(goType string) bool {

pkg/writers/bun/writer_test.go

@@ -1,6 +1,8 @@
 package bun
 
 import (
+	"go/parser"
+	"go/token"
 	"os"
 	"path/filepath"
 	"strings"
@@ -95,6 +97,29 @@ func TestWriter_WriteTable(t *testing.T) {
 	}
 }
 
+func TestWriter_WriteTable_MultilineDescriptionProducesValidGo(t *testing.T) {
+	table := models.InitTable("city", "info")
+	table.Description = "Cities and municipalities worldwide.\n\nSPATIAL:\nProximity queries use a GiST index."
+	table.Columns["id_city"] = &models.Column{Name: "id_city", Type: "integer", IsPrimaryKey: true, NotNull: true}
+
+	outputPath := filepath.Join(t.TempDir(), "city.go")
+	writer := NewWriter(&writers.WriterOptions{OutputPath: outputPath, PackageName: "models"})
+	if err := writer.WriteTable(table); err != nil {
+		t.Fatalf("WriteTable() error = %v", err)
+	}
+
+	generated, err := os.ReadFile(outputPath)
+	if err != nil {
+		t.Fatalf("failed to read generated code: %v", err)
+	}
+	if _, err := parser.ParseFile(token.NewFileSet(), outputPath, generated, parser.AllErrors); err != nil {
+		t.Fatalf("generated code is invalid Go: %v\n%s", err, generated)
+	}
+	if !strings.Contains(string(generated), "// Cities and municipalities worldwide. SPATIAL: Proximity queries use a GiST index.") {
+		t.Errorf("multiline description was not rendered as a single Go comment:\n%s", generated)
+	}
+}
+
 func TestWriter_WriteDatabase_MultiFile(t *testing.T) {
 	// Create a database with two tables
 	db := models.InitDatabase("testdb")

pkg/writers/dbml/writer.go

@@ -196,8 +196,12 @@ func (w *Writer) tableToDBML(t *models.Table) string {
 
 	note := strings.TrimSpace(t.Description + " " + t.Comment)
 	if note != "" {
+		if strings.Contains(note, "\n") {
+			fmt.Fprintf(&sb, "\n  Note: '''\n%s\n  '''\n", note)
+		} else {
 			fmt.Fprintf(&sb, "\n  Note: '%s'\n", note)
 		}
+	}
 
 	sb.WriteString("}\n")
 	return sb.String()

pkg/writers/dbml/writer_test.go

@@ -59,6 +59,23 @@ func TestWriter_WriteTable(t *testing.T) {
 	assert.Contains(t, output, "Note: 'User accounts table'")
 }
 
+func TestWriter_WriteTable_MultilineNote(t *testing.T) {
+	table := models.InitTable("cities", "info")
+	table.Description = "Cities and municipalities worldwide.\n\nSPATIAL:\nProximity queries use a GiST index."
+
+	outputPath := filepath.Join(t.TempDir(), "cities.dbml")
+	writer := NewWriter(&writers.WriterOptions{OutputPath: outputPath})
+	if err := writer.WriteTable(table); err != nil {
+		t.Fatalf("WriteTable() error = %v", err)
+	}
+
+	output, err := os.ReadFile(outputPath)
+	if err != nil {
+		t.Fatalf("failed to read generated DBML: %v", err)
+	}
+	assert.Contains(t, string(output), "Note: '''\nCities and municipalities worldwide.\n\nSPATIAL:\nProximity queries use a GiST index.\n  '''")
+}
+
 func TestWriter_WriteDatabase_WithRelationships(t *testing.T) {
 	db := models.InitDatabase("test_db")
 	schema := models.InitSchema("public")

pkg/writers/drizzle/template_data.go

@@ -2,6 +2,7 @@ package drizzle
 
 import (
 	"sort"
+	"strings"
 
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 )
@@ -199,13 +200,16 @@ func NewIndexData(index *models.Index, tableVar string, tm *TypeMapper) *IndexDa
 
 // formatComment combines description and comment into a single comment string
 func formatComment(description, comment string) string {
+	var result string
 	if description != "" && comment != "" {
-		return description + " - " + comment
+		result = description + " - " + comment
+	} else if description != "" {
+		result = description
+	} else {
+		result = comment
 	}
-	if description != "" {
+	// Generated TypeScript comments are emitted on a single source line.
-		return description
+	return strings.Join(strings.Fields(result), " ")
-	}
-	return comment
 }
 
 // joinStrings joins a slice of strings with a separator

pkg/writers/gorm/template_data.go

@@ -192,13 +192,17 @@ func (md *ModelData) AddRelationshipField(field *FieldData) {
 
 // formatComment combines description and comment into a single comment string
 func formatComment(description, comment string) string {
+	var result string
 	if description != "" && comment != "" {
-		return description + " - " + comment
+		result = description + " - " + comment
+	} else if description != "" {
+		result = description
+	} else {
+		result = comment
 	}
-	if description != "" {
+	// Generated Go comments are emitted on a single source line. Collapse
-		return description
+	// multiline DBML notes so the remaining lines cannot become invalid Go.
-	}
+	return strings.Join(strings.Fields(result), " ")
-	return comment
 }
 
 func isStringLikePrimaryKeyType(goType string) bool {

pkg/writers/gorm/writer_test.go

@@ -1,6 +1,8 @@
 package gorm
 
 import (
+	"go/parser"
+	"go/token"
 	"os"
 	"path/filepath"
 	"strings"
@@ -87,6 +89,29 @@ func TestWriter_WriteTable(t *testing.T) {
 	}
 }
 
+func TestWriter_WriteTable_MultilineDescriptionProducesValidGo(t *testing.T) {
+	table := models.InitTable("cities", "info")
+	table.Description = "Cities and municipalities worldwide.\n\nSPATIAL:\nProximity queries use a GiST index."
+	table.Columns["id"] = &models.Column{Name: "id", Type: "integer", IsPrimaryKey: true, NotNull: true}
+
+	outputPath := filepath.Join(t.TempDir(), "cities.go")
+	writer := NewWriter(&writers.WriterOptions{OutputPath: outputPath, PackageName: "models"})
+	if err := writer.WriteTable(table); err != nil {
+		t.Fatalf("WriteTable() error = %v", err)
+	}
+
+	generated, err := os.ReadFile(outputPath)
+	if err != nil {
+		t.Fatalf("failed to read generated code: %v", err)
+	}
+	if _, err := parser.ParseFile(token.NewFileSet(), outputPath, generated, parser.AllErrors); err != nil {
+		t.Fatalf("generated code is invalid Go: %v\n%s", err, generated)
+	}
+	if !strings.Contains(string(generated), "// Cities and municipalities worldwide. SPATIAL: Proximity queries use a GiST index.") {
+		t.Errorf("multiline description was not rendered as a single Go comment:\n%s", generated)
+	}
+}
+
 func TestWriter_WriteDatabase_MultiFile(t *testing.T) {
 	// Create a database with two tables
 	db := models.InitDatabase("testdb")

pkg/writers/pgsql/writer.go

@@ -1980,7 +1980,8 @@ func (w *Writer) executeDatabaseSQL(db *models.Database, connString string) erro
 		Errors:    make([]ExecutionError, 0),
 	}
 
-	// Generate SQL statements
+	// Generating a large schema can take time before any statement is executed.
+	fmt.Fprintln(os.Stderr, "      → Generating PostgreSQL statements...")
 	statements, err := w.GenerateDatabaseStatements(db)
 	if err != nil {
 		return fmt.Errorf("failed to generate SQL statements: %w", err)
@@ -1989,12 +1990,14 @@ func (w *Writer) executeDatabaseSQL(db *models.Database, connString string) erro
 	w.executionReport.TotalStatements = len(statements)
 
 	// Connect to database
+	fmt.Fprintln(os.Stderr, "      → Connecting to PostgreSQL output database...")
 	ctx := context.Background()
 	conn, err := pgsql.Connect(ctx, connString, "writer-pgsql")
 	if err != nil {
 		return fmt.Errorf("failed to connect to database: %w", err)
 	}
 	defer conn.Close(ctx)
+	fmt.Fprintln(os.Stderr, "      → Connected. Executing statements...")
 
 	// Track schemas and tables
 	schemaMap := make(map[string]*SchemaReport)