Merge pull request 'Feat generated headers column order' (#28) from feat-generated-headers-column-order into master

Reviewed-on: #28

Makefile

@@ -22,7 +22,7 @@ GOVULNCHECK   = go run golang.org/x/vuln/cmd/govulncheck@latest
 # Version information
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 BUILD_DATE := $(shell date -u +"%Y-%m-%d %H:%M:%S UTC")
-LDFLAGS := -X 'main.version=$(VERSION)' -X 'main.buildDate=$(BUILD_DATE)'
+LDFLAGS := -X 'git.warky.dev/wdevs/relspecgo/pkg/buildinfo.Version=$(VERSION)' -X 'git.warky.dev/wdevs/relspecgo/pkg/buildinfo.BuildDate=$(BUILD_DATE)'
 
 # Auto-detect container runtime (Docker or Podman)
 CONTAINER_RUNTIME := $(shell \
@@ -207,7 +207,7 @@ docker-test-integration: docker-up ## Start DB and run integration tests
 		$(GOTEST) -v ./pkg/readers/pgsql/ -count=1 || (make docker-down && exit 1)
 	@make docker-down
 
-release: ## Create and push a new release tag (auto-increments patch version)
+release: lint fmt-check test build ## Run lint, format check, tests, build, then create and push a new release tag
 	@echo "Creating new release..."
 	@latest_tag=$$(git describe --tags --abbrev=0 2>/dev/null || echo ""); \
 	if [ -z "$$latest_tag" ]; then \

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

@@ -5,10 +5,43 @@ import (
 	"os"
 )
 
+// asciiLogo (see version.go) is printed by the `version` command.
+
 func main() {
-	printVersionHeader(os.Args[1:])
-	if err := rootCmd.Execute(); err != nil {
+	args := os.Args[1:]
+	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

@@ -2,51 +2,23 @@ package main
 
 import (
 	"fmt"
-	"runtime/debug"
-	"time"
 
 	"github.com/spf13/cobra"
+
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 )
 
+// version/buildDate mirror pkg/buildinfo so existing call sites keep working.
+// The actual values are set there via ldflags (see Makefile).
 var (
-	// Version information, set via ldflags during build
-	version          = "dev"
-	buildDate        = "unknown"
+	version          = buildinfo.Version
+	buildDate        = buildinfo.BuildDate
 	prisma7          bool
 	noVersion        bool
+	silent           bool
 	strictDirectives bool
 )
 
-func init() {
-	// If version wasn't set via ldflags, try to get it from build info
-	if version == "dev" {
-		if info, ok := debug.ReadBuildInfo(); ok {
-			// Try to get version from VCS
-			var vcsRevision, vcsTime string
-			for _, setting := range info.Settings {
-				switch setting.Key {
-				case "vcs.revision":
-					if len(setting.Value) >= 7 {
-						vcsRevision = setting.Value[:7]
-					}
-				case "vcs.time":
-					vcsTime = setting.Value
-				}
-			}
-
-			if vcsRevision != "" {
-				version = vcsRevision
-			}
-
-			if vcsTime != "" {
-				if t, err := time.Parse(time.RFC3339, vcsTime); err == nil {
-					buildDate = t.UTC().Format("2006-01-02 15:04:05 UTC")
-				}
-			}
-		}
-	}
-}
-
 var rootCmd = &cobra.Command{
 	Use:   "relspec",
 	Short: "RelSpec - Database schema conversion and analysis tool",
@@ -73,6 +45,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:, …)")
 }
 

cmd/relspec/version.go

@@ -4,13 +4,16 @@ import (
 	"fmt"
 
 	"github.com/spf13/cobra"
+
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 )
 
 var versionCmd = &cobra.Command{
 	Use:   "version",
 	Short: "Print version information",
 	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Printf("RelSpec %s\n", version)
-		fmt.Printf("Built: %s\n", buildDate)
+		fmt.Print(buildinfo.AsciiLogo)
+		fmt.Printf("RelSpec %s\n", buildinfo.Version)
+		fmt.Printf("Built: %s\n", buildinfo.BuildDate)
 	},
 }

pkg/buildinfo/buildinfo.go

@@ -0,0 +1,65 @@
+// Package buildinfo exposes the RelSpec version and build date so that both the
+// CLI and the schema writers can stamp generated output with the same values.
+package buildinfo
+
+import (
+	"fmt"
+	"runtime/debug"
+	"time"
+)
+
+// Version and BuildDate are set via -ldflags at build time (see Makefile). When
+// built without ldflags they are backfilled from the Go module build info.
+var (
+	Version   = "dev"
+	BuildDate = "unknown"
+)
+
+func init() {
+	if Version != "dev" {
+		return
+	}
+	info, ok := debug.ReadBuildInfo()
+	if !ok {
+		return
+	}
+	var rev, vcsTime string
+	for _, s := range info.Settings {
+		switch s.Key {
+		case "vcs.revision":
+			if len(s.Value) >= 7 {
+				rev = s.Value[:7]
+			}
+		case "vcs.time":
+			vcsTime = s.Value
+		}
+	}
+	if rev != "" {
+		Version = rev
+	}
+	if t, err := time.Parse(time.RFC3339, vcsTime); err == nil {
+		BuildDate = t.UTC().Format("2006-01-02 15:04:05 UTC")
+	}
+}
+
+// GeneratedComment returns the one-line provenance string embedded in generated
+// files, e.g. "RelSpec dev (built: unknown)".
+func GeneratedComment() string {
+	return fmt.Sprintf("RelSpec %s (built: %s)", Version, BuildDate)
+}
+
+const AsciiLogo = `
+██████╗ ███████╗██╗     ███████╗██████╗ ███████╗ ██████╗
+██╔══██╗██╔════╝██║     ██╔════╝██╔══██╗██╔════╝██╔════╝
+██████╔╝█████╗  ██║     ███████╗██████╔╝█████╗  ██║
+██╔══██╗██╔══╝  ██║     ╚════██║██╔═══╝ ██╔══╝  ██║
+██║  ██║███████╗███████╗███████║██║     ███████╗╚██████╗
+╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝╚═╝     ╚══════╝ ╚═════╝
+[ IN ] ──▶ [ RELSPEC ] ──▶ [ OUT ]
+╔══════════════════════════════════════╗
+║                                      ║
+║   © WARKY DEVS                       ║
+║   Author: Hein (hein@warky.dev)      ║
+║                                      ║
+╚══════════════════════════════════════╝
+`

pkg/readers/dbml/reader.go

@@ -305,9 +305,39 @@ func sortDBMLFiles(files []string) []string {
 // Merges: Columns (map), Constraints (map), Indexes (map), Relationships (map)
 // Uses first non-empty Description
 func mergeTable(baseTable, fileTable *models.Table) {
-	// Merge columns (map naturally merges - later keys overwrite)
-	for key, col := range fileTable.Columns {
-		baseTable.Columns[key] = col
+	// Merge columns. Each file numbers its own columns from 1, so a table split
+	// across files would otherwise end up with colliding Column.Sequence values
+	// and writers would fall back to alphabetical order. Re-base the incoming
+	// file's new columns after the highest sequence already present, preserving
+	// their in-file order. Columns that overwrite an existing key keep the
+	// original position.
+	var maxSeq uint
+	for _, col := range baseTable.Columns {
+		if col.Sequence > maxSeq {
+			maxSeq = col.Sequence
+		}
+	}
+
+	incoming := make([]*models.Column, 0, len(fileTable.Columns))
+	for _, col := range fileTable.Columns {
+		incoming = append(incoming, col)
+	}
+	sort.Slice(incoming, func(i, j int) bool {
+		if incoming[i].Sequence != incoming[j].Sequence {
+			return incoming[i].Sequence < incoming[j].Sequence
+		}
+		return incoming[i].Name < incoming[j].Name
+	})
+
+	var added uint
+	for _, col := range incoming {
+		if existing, ok := baseTable.Columns[col.Name]; ok {
+			col.Sequence = existing.Sequence
+		} else {
+			added++
+			col.Sequence = maxSeq + added
+		}
+		baseTable.Columns[col.Name] = col
 	}
 
 	// Merge constraints
@@ -434,6 +464,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 +476,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 +587,18 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 			continue
 		}
 
-		// Parse table note
-		if inTable && currentTable != nil && strings.HasPrefix(line, "Note:") {
-			note := strings.TrimPrefix(line, "Note:")
+		// Parse table note. DBML files in the wild use both `Note:` and
+		// `note:`, so accept either spelling.
+		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 +635,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 +685,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 +716,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 +799,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

@@ -652,6 +652,22 @@ func TestReadDirectory_TableMerging(t *testing.T) {
 	if emailCol.Type != "varchar(255)" {
 		t.Errorf("Expected email type 'varchar(255)', got '%s'", emailCol.Type)
 	}
+
+	// Merged columns must keep declaration order (file 1: id, email; file 3:
+	// name, created_at) via strictly increasing, non-colliding Sequence values
+	// so downstream writers do not fall back to alphabetical order.
+	order := []string{"id", "email", "name", "created_at"}
+	var prev uint
+	for i, name := range order {
+		col := usersTable.Columns[name]
+		if col.Sequence == 0 {
+			t.Fatalf("column %q has zero Sequence after merge", name)
+		}
+		if i > 0 && col.Sequence <= prev {
+			t.Errorf("column %q Sequence %d not greater than previous %d (order not preserved across files)", name, col.Sequence, prev)
+		}
+		prev = col.Sequence
+	}
 }
 
 func TestReadDirectory_CommentedRefsLast(t *testing.T) {
@@ -1033,3 +1049,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

@@ -6,6 +6,7 @@ import (
 	"sort"
 	"strings"
 
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 	"git.warky.dev/wdevs/relspecgo/pkg/writers"
 )
@@ -13,6 +14,7 @@ import (
 // TemplateData represents the data passed to the template for code generation
 type TemplateData struct {
 	PackageName string
+	GeneratedBy string
 	Imports     []string
 	Models      []*ModelData
 	Config      *MethodConfig
@@ -165,6 +167,7 @@ func NewTemplateData(packageName string, config *MethodConfig) *TemplateData {
 
 	return &TemplateData{
 		PackageName: packageName,
+		GeneratedBy: buildinfo.GeneratedComment(),
 		Imports:     make([]string, 0),
 		Models:      make([]*ModelData, 0),
 		Config:      config,
@@ -279,13 +282,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 != "" {
-		return description
-	}
-	return comment
+	// Generated Go comments are emitted on a single source line.
+	return strings.Join(strings.Fields(result), " ")
 }
 
 func isStringLikePrimaryKeyType(goType string) bool {

pkg/writers/bun/templates.go

@@ -7,7 +7,8 @@ import (
 
 // modelTemplate defines the template for generating Bun models
 const modelTemplate = `// Code generated by relspecgo. DO NOT EDIT.
-package {{.PackageName}}
+{{if .GeneratedBy}}// {{.GeneratedBy}}
+{{end}}package {{.PackageName}}
 
 {{if .Imports -}}
 import (

pkg/writers/bun/writer_test.go

@@ -1,11 +1,14 @@
 package bun
 
 import (
+	"go/parser"
+	"go/token"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 	"git.warky.dev/wdevs/relspecgo/pkg/writers"
 )
@@ -95,6 +98,65 @@ 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_WriteTable_EmbedsRelspecVersionHeader(t *testing.T) {
+	table := models.InitTable("users", "public")
+	table.Columns["id"] = &models.Column{Name: "id", Type: "bigint", IsPrimaryKey: true, NotNull: true, Sequence: 1}
+
+	outputPath := filepath.Join(t.TempDir(), "users.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)
+	}
+	src := string(generated)
+
+	if _, err := parser.ParseFile(token.NewFileSet(), outputPath, generated, parser.AllErrors); err != nil {
+		t.Fatalf("generated code is invalid Go: %v\n%s", err, src)
+	}
+
+	wantHeader := "// " + buildinfo.GeneratedComment()
+	if !strings.Contains(src, wantHeader) {
+		t.Errorf("generated code missing RelSpec version header %q\n%s", wantHeader, src)
+	}
+	// The provenance comment must sit between the "Code generated" marker and the package clause.
+	genIdx := strings.Index(src, "// Code generated by relspecgo. DO NOT EDIT.")
+	hdrIdx := strings.Index(src, wantHeader)
+	pkgIdx := strings.Index(src, "package models")
+	if genIdx < 0 || hdrIdx < 0 || pkgIdx < 0 || !(genIdx < hdrIdx && hdrIdx < pkgIdx) {
+		t.Errorf("RelSpec version header is misplaced (gen=%d hdr=%d pkg=%d)\n%s", genIdx, hdrIdx, pkgIdx, src)
+	}
+	if !strings.Contains(wantHeader, "RelSpec ") || !strings.Contains(wantHeader, "(built: ") {
+		t.Errorf("version header not in expected 'RelSpec <version> (built: <date>)' form: %q", wantHeader)
+	}
+}
+
 func TestWriter_WriteDatabase_MultiFile(t *testing.T) {
 	// Create a database with two tables
 	db := models.InitDatabase("testdb")

pkg/writers/dbml/writer.go

@@ -196,7 +196,11 @@ func (w *Writer) tableToDBML(t *models.Table) string {
 
 	note := strings.TrimSpace(t.Description + " " + t.Comment)
 	if note != "" {
-		fmt.Fprintf(&sb, "\n  Note: '%s'\n", 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")

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,15 +2,18 @@ package drizzle
 
 import (
 	"sort"
+	"strings"
 
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 )
 
 // TemplateData represents the data passed to the template for code generation
 type TemplateData struct {
-	Imports []string
-	Enums   []*EnumData
-	Tables  []*TableData
+	GeneratedBy string
+	Imports     []string
+	Enums       []*EnumData
+	Tables      []*TableData
 }
 
 // EnumData represents an enum in the schema
@@ -58,9 +61,10 @@ type IndexData struct {
 // NewTemplateData creates a new TemplateData
 func NewTemplateData() *TemplateData {
 	return &TemplateData{
-		Imports: make([]string, 0),
-		Enums:   make([]*EnumData, 0),
-		Tables:  make([]*TableData, 0),
+		GeneratedBy: buildinfo.GeneratedComment(),
+		Imports:     make([]string, 0),
+		Enums:       make([]*EnumData, 0),
+		Tables:      make([]*TableData, 0),
 	}
 }
 
@@ -199,13 +203,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 != "" {
-		return description
-	}
-	return comment
+	// Generated TypeScript comments are emitted on a single source line.
+	return strings.Join(strings.Fields(result), " ")
 }
 
 // joinStrings joins a slice of strings with a separator

pkg/writers/drizzle/templates.go

@@ -7,7 +7,8 @@ import (
 
 // schemaTemplate defines the template for generating Drizzle schemas
 const schemaTemplate = `// Code generated by relspecgo. DO NOT EDIT.
-{{range .Imports}}{{.}}
+{{if .GeneratedBy}}// {{.GeneratedBy}}
+{{end}}{{range .Imports}}{{.}}
 {{end}}
 {{if .Enums}}
 // Enums

pkg/writers/gorm/template_data.go

@@ -4,6 +4,7 @@ import (
 	"sort"
 	"strings"
 
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 	"git.warky.dev/wdevs/relspecgo/pkg/writers"
 )
@@ -11,6 +12,7 @@ import (
 // TemplateData represents the data passed to the template for code generation
 type TemplateData struct {
 	PackageName string
+	GeneratedBy string
 	Imports     []string
 	Models      []*ModelData
 	Config      *MethodConfig
@@ -79,6 +81,7 @@ func NewTemplateData(packageName string, config *MethodConfig) *TemplateData {
 
 	return &TemplateData{
 		PackageName: packageName,
+		GeneratedBy: buildinfo.GeneratedComment(),
 		Imports:     make([]string, 0),
 		Models:      make([]*ModelData, 0),
 		Config:      config,
@@ -192,13 +195,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 != "" {
-		return description
-	}
-	return comment
+	// Generated Go comments are emitted on a single source line. Collapse
+	// multiline DBML notes so the remaining lines cannot become invalid Go.
+	return strings.Join(strings.Fields(result), " ")
 }
 
 func isStringLikePrimaryKeyType(goType string) bool {

pkg/writers/gorm/templates.go

@@ -7,7 +7,8 @@ import (
 
 // modelTemplate defines the template for generating GORM models
 const modelTemplate = `// Code generated by relspecgo. DO NOT EDIT.
-package {{.PackageName}}
+{{if .GeneratedBy}}// {{.GeneratedBy}}
+{{end}}package {{.PackageName}}
 
 {{if .Imports -}}
 import (

pkg/writers/gorm/writer_test.go

@@ -1,6 +1,8 @@
 package gorm
 
 import (
+	"go/parser"
+	"go/token"
 	"os"
 	"path/filepath"
 	"strings"
@@ -87,6 +89,69 @@ 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_WriteTable_ColumnOrderFollowsSequence(t *testing.T) {
+	// Column.Sequence carries the source (e.g. DBML) declaration order; the
+	// generated struct fields must follow it, not fall back to alphabetical.
+	table := models.InitTable("widget", "public")
+	table.Columns["zeta"] = &models.Column{Name: "zeta", Type: "varchar", Length: 50, Sequence: 1}
+	table.Columns["alpha"] = &models.Column{Name: "alpha", Type: "bigint", NotNull: true, IsPrimaryKey: true, AutoIncrement: true, Sequence: 2}
+	table.Columns["mid_field"] = &models.Column{Name: "mid_field", Type: "integer", Sequence: 3}
+	table.Columns["beta"] = &models.Column{Name: "beta", Type: "varchar", Length: 100, Sequence: 4}
+
+	outputPath := filepath.Join(t.TempDir(), "widget.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)
+	}
+	src := string(generated)
+	if _, err := parser.ParseFile(token.NewFileSet(), outputPath, generated, parser.AllErrors); err != nil {
+		t.Fatalf("generated code is invalid Go: %v\n%s", err, src)
+	}
+
+	positions := make([]int, 0, 4)
+	for _, field := range []string{"Zeta ", "Alpha ", "MidField ", "Beta "} {
+		idx := strings.Index(src, "\t"+field)
+		if idx < 0 {
+			t.Fatalf("field %q missing from generated struct:\n%s", field, src)
+		}
+		positions = append(positions, idx)
+	}
+	for i := 1; i < len(positions); i++ {
+		if positions[i] <= positions[i-1] {
+			t.Errorf("struct fields not in Sequence order (want zeta, alpha, mid_field, beta):\n%s", src)
+			break
+		}
+	}
+}
+
 func TestWriter_WriteDatabase_MultiFile(t *testing.T) {
 	// Create a database with two tables
 	db := models.InitDatabase("testdb")

pkg/writers/mssql/writer.go

@@ -11,6 +11,7 @@ import (
 
 	_ "github.com/microsoft/go-mssqldb" // MSSQL driver
 
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 	"git.warky.dev/wdevs/relspecgo/pkg/mssql"
 	"git.warky.dev/wdevs/relspecgo/pkg/writers"
@@ -68,7 +69,7 @@ func (w *Writer) WriteDatabase(db *models.Database) error {
 	// Write header comment
 	fmt.Fprintf(w.writer, "-- MSSQL Database Schema\n")
 	fmt.Fprintf(w.writer, "-- Database: %s\n", db.Name)
-	fmt.Fprintf(w.writer, "-- Generated by RelSpec\n\n")
+	fmt.Fprintf(w.writer, "-- Generated by %s\n\n", buildinfo.GeneratedComment())
 
 	// Process each schema in the database
 	for _, schema := range db.Schemas {
@@ -477,7 +478,7 @@ func (w *Writer) executeDatabaseSQL(db *models.Database, connString string) erro
 	statements := []string{}
 	statements = append(statements, "-- MSSQL Database Schema")
 	statements = append(statements, fmt.Sprintf("-- Database: %s", db.Name))
-	statements = append(statements, "-- Generated by RelSpec")
+	statements = append(statements, "-- Generated by "+buildinfo.GeneratedComment())
 
 	for _, schema := range db.Schemas {
 		if err := w.generateSchemaStatements(schema, &statements); err != nil {

pkg/writers/pgsql/migration_writer.go

@@ -7,6 +7,7 @@ import (
 	"sort"
 	"strings"
 
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 	"git.warky.dev/wdevs/relspecgo/pkg/pgsql"
 	"git.warky.dev/wdevs/relspecgo/pkg/writers"
@@ -143,7 +144,7 @@ func (w *MigrationWriter) WriteMigration(model, current *models.Database) error
 
 	// Write header
 	fmt.Fprintf(w.writer, "-- PostgreSQL Migration Script\n")
-	fmt.Fprintf(w.writer, "-- Generated by RelSpec\n")
+	fmt.Fprintf(w.writer, "-- Generated by %s\n", buildinfo.GeneratedComment())
 	fmt.Fprintf(w.writer, "-- Source: %s -> %s\n", current.Name, model.Name)
 	if w.options.ContinueOnError {
 		fmt.Fprintf(w.writer, "\\set ON_ERROR_STOP off\n")

pkg/writers/pgsql/writer.go

@@ -12,6 +12,7 @@ import (
 	"sync"
 	"time"
 
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 	"git.warky.dev/wdevs/relspecgo/pkg/pgsql"
 	"git.warky.dev/wdevs/relspecgo/pkg/writers"
@@ -101,7 +102,7 @@ func (w *Writer) WriteDatabase(db *models.Database) error {
 	// Write header comment
 	fmt.Fprintf(w.writer, "-- PostgreSQL Database Schema\n")
 	fmt.Fprintf(w.writer, "-- Database: %s\n", db.Name)
-	fmt.Fprintf(w.writer, "-- Generated by RelSpec\n")
+	fmt.Fprintf(w.writer, "-- Generated by %s\n", buildinfo.GeneratedComment())
 	if w.options.ContinueOnError {
 		fmt.Fprintf(w.writer, "\\set ON_ERROR_STOP off\n")
 	}
@@ -125,7 +126,7 @@ func (w *Writer) GenerateDatabaseStatements(db *models.Database) ([]string, erro
 	// Add header comment
 	statements = append(statements, "-- PostgreSQL Database Schema")
 	statements = append(statements, fmt.Sprintf("-- Database: %s", db.Name))
-	statements = append(statements, "-- Generated by RelSpec")
+	statements = append(statements, "-- Generated by "+buildinfo.GeneratedComment())
 
 	// Process each schema in the database
 	for _, schema := range db.Schemas {
@@ -555,7 +556,7 @@ func (w *Writer) GenerateAddColumnsForDatabase(db *models.Database) ([]string, e
 
 	statements = append(statements, "-- Add missing columns to existing tables")
 	statements = append(statements, fmt.Sprintf("-- Database: %s", db.Name))
-	statements = append(statements, "-- Generated by RelSpec")
+	statements = append(statements, "-- Generated by "+buildinfo.GeneratedComment())
 
 	for _, schema := range db.Schemas {
 		schemaStatements, err := w.GenerateAddColumnStatements(schema)
@@ -1446,19 +1447,10 @@ func (w *Writer) writeComments(schema *models.Schema) error {
 
 // Helper functions
 
-// getSortedColumns returns columns sorted by name
+// getSortedColumns returns columns sorted by Sequence then Name, preserving the
+// original column order from the source schema for deterministic output.
 func getSortedColumns(columns map[string]*models.Column) []*models.Column {
-	names := make([]string, 0, len(columns))
-	for name := range columns {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-
-	sorted := make([]*models.Column, 0, len(columns))
-	for _, name := range names {
-		sorted = append(sorted, columns[name])
-	}
-	return sorted
+	return sortColumns(columns)
 }
 
 // isIntegerType checks if a column type is an integer type
@@ -1980,7 +1972,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 +1982,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)

pkg/writers/sqlite/writer.go

@@ -10,6 +10,7 @@ import (
 
 	_ "modernc.org/sqlite" // SQLite driver
 
+	"git.warky.dev/wdevs/relspecgo/pkg/buildinfo"
 	"git.warky.dev/wdevs/relspecgo/pkg/models"
 	"git.warky.dev/wdevs/relspecgo/pkg/writers"
 )
@@ -72,7 +73,7 @@ func (w *Writer) writeContent(db *models.Database) error {
 	// Write header comment
 	fmt.Fprintf(w.writer, "-- SQLite Database Schema\n")
 	fmt.Fprintf(w.writer, "-- Database: %s\n", db.Name)
-	fmt.Fprintf(w.writer, "-- Generated by RelSpec\n")
+	fmt.Fprintf(w.writer, "-- Generated by %s\n", buildinfo.GeneratedComment())
 	fmt.Fprintf(w.writer, "-- Note: SQLite has no schema concept; non-default schema names are flattened into table name prefixes (e.g., auth.sessions -> auth_sessions)\n\n")
 
 	// Enable foreign keys