feat(dbml): @postgres/@sqlite dialect directives (#19)

Add parseable `@<namespace>[(<target>)]: <args>` directives embedded in DBML.
They are stored losslessly on each object's Metadata, round-trip unchanged
through the DBML writer, and are translated to SQL only by the writer for the
matching dialect.

- models: Directive type + catalog; Metadata map added to Column and Index
- dbml reader: parse and attach directives at database/table/column/index
  level; line-numbered errors; repeatable by default with singleton duplicate
  detection. Fixes a preexisting bug where an `indexes {}` closing brace ended
  the table early, dropping trailing Note: and directive lines.
- dbml writer: re-emit directives at their location; idempotent output
- pgsql writer: PARTITION BY / INHERITS / WITH / TABLESPACE (table),
  STORAGE / COMPRESSION / identity (column), WITH / TABLESPACE (index)
- sqlite writer: WITHOUT ROWID / STRICT (table), COLLATE (column)
- --strict-directives flag on ReaderOptions and WriterOptions
- docs/DBML_DIRECTIVES.md + reader/writer READMEs

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ss2MY5J11cRGwEz86ZXk7d

pkg/readers/dbml/README.md

@@ -93,6 +93,50 @@ Ref: posts.user_id > users.id [delete: cascade]
 - Indexes and composite indexes
 - Table notes and column notes
 - Enums
+- Dialect directives (`@postgres:` / `@sqlite:` — see below)
+
+## Dialect directives
+
+Lines of the form `@<namespace>[(<column>)]: <args>` embed database-specific
+features that plain DBML cannot express (partitioning, `WITHOUT ROWID`,
+tablespaces, index storage parameters, …). They are stored losslessly on the
+relevant object's `Metadata` and round-trip unchanged through the DBML writer;
+the PostgreSQL and SQLite writers translate the ones they understand to SQL.
+
+```dbml
+@postgres: search_path myapp
+
+Table myapp.events {
+  id bigint [pk]
+  created_at timestamp [not null]
+  @postgres(id): identity always
+  @postgres: partition by RANGE (created_at)
+  @sqlite: without rowid
+
+  indexes {
+    (created_at) [name: 'idx_events_created']
+    @postgres: with (fillfactor=90)
+  }
+}
+```
+
+| Position | Attaches to |
+|----------|-------------|
+| Before the first `Table {` | database |
+| Table body, no `(target)` | that table |
+| Table body, `(col)` target | column `col` (error if unknown) |
+| Inside `indexes { }` | the most recently listed index entry |
+
+`args` is preserved verbatim; the **key** (lowercased first token) drives
+duplicate detection. Repeated directives are kept in order; catalog "singleton"
+keys error on a second occurrence at the same location. All errors are
+line-numbered.
+
+`ReaderOptions.StrictDirectives` (CLI `--strict-directives`) turns an unknown
+namespace or key into an error instead of preserving it silently.
+
+See [`docs/DBML_DIRECTIVES.md`](../../../docs/DBML_DIRECTIVES.md) for the full
+grammar and the supported-directive matrix.
 
 ## Notes
 

pkg/readers/dbml/directives.go

@@ -0,0 +1,137 @@
+package dbml
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"git.warky.dev/wdevs/relspecgo/pkg/models"
+)
+
+// directiveLineRegex matches a dialect directive line:
+//
+//	@postgres: partition by RANGE (created_at)
+//	@postgres(id): identity always
+//
+// Group 1 is the namespace, group 2 the optional (column) target, group 3 the
+// raw argument text (validated separately so error messages can be specific).
+var directiveLineRegex = regexp.MustCompile(`^@([^():]*)(?:\(([^()]*)\))?\s*:(.*)$`)
+
+// namespaceRegex is the grammar for a directive namespace.
+var namespaceRegex = regexp.MustCompile(`^[a-z][a-z0-9_]*$`)
+
+// parsedDirective is a directive line that has been parsed but not yet attached
+// to a model object.
+type parsedDirective struct {
+	namespace string
+	target    string // column name; "" when absent
+	args      string
+	line      int
+}
+
+// parseDirectiveLine parses a single "@namespace[(target)]: args" line.
+func parseDirectiveLine(line string, lineNo int) (parsedDirective, error) {
+	m := directiveLineRegex.FindStringSubmatch(line)
+	if m == nil {
+		return parsedDirective{}, fmt.Errorf(
+			"dbml: line %d: malformed directive %q (expected \"@namespace: args\")", lineNo, line)
+	}
+
+	ns := strings.TrimSpace(m[1])
+	target := strings.TrimSpace(m[2])
+	args := strings.TrimSpace(m[3])
+
+	if !namespaceRegex.MatchString(ns) {
+		return parsedDirective{}, fmt.Errorf(
+			"dbml: line %d: invalid directive namespace %q (must match [a-z][a-z0-9_]*)", lineNo, ns)
+	}
+	if args == "" {
+		return parsedDirective{}, fmt.Errorf("dbml: line %d: directive @%s has no arguments", lineNo, ns)
+	}
+	if target != "" {
+		target = stripQuotes(target)
+	}
+
+	return parsedDirective{namespace: ns, target: target, args: args, line: lineNo}, nil
+}
+
+// attachDirective resolves the target model object from the current parser state
+// and stores the directive in its Metadata, enforcing location, duplicate and
+// strict-mode rules.
+func (r *Reader) attachDirective(
+	pd parsedDirective,
+	db *models.Database,
+	table *models.Table,
+	inTable, inIndexes bool,
+	lastIndex *models.Index,
+) error {
+	strict := r.options != nil && r.options.StrictDirectives
+	key := models.DirectiveKey(pd.args)
+
+	var meta map[string]any
+	var location string
+
+	switch {
+	case inIndexes:
+		if pd.target != "" {
+			return fmt.Errorf("dbml: line %d: directive target (%s) is not allowed inside an indexes block", pd.line, pd.target)
+		}
+		if lastIndex == nil {
+			return fmt.Errorf("dbml: line %d: directive @%s must follow an index definition", pd.line, pd.namespace)
+		}
+		if lastIndex.Metadata == nil {
+			lastIndex.Metadata = make(map[string]any)
+		}
+		meta = lastIndex.Metadata
+		location = models.DirectiveLocationIndex
+
+	case inTable && table != nil:
+		if pd.target != "" {
+			col, ok := table.Columns[pd.target]
+			if !ok {
+				return fmt.Errorf("dbml: line %d: directive target column %q not found in table %q", pd.line, pd.target, table.Name)
+			}
+			if col.Metadata == nil {
+				col.Metadata = make(map[string]any)
+			}
+			meta = col.Metadata
+			location = models.DirectiveLocationColumn
+		} else {
+			if table.Metadata == nil {
+				table.Metadata = make(map[string]any)
+			}
+			meta = table.Metadata
+			location = models.DirectiveLocationTable
+		}
+
+	default:
+		if pd.target != "" {
+			return fmt.Errorf("dbml: line %d: directive target (%s) is only valid inside a table", pd.line, pd.target)
+		}
+		if db.Metadata == nil {
+			db.Metadata = make(map[string]any)
+		}
+		meta = db.Metadata
+		location = models.DirectiveLocationDatabase
+	}
+
+	spec, documented := models.LookupDirectiveSpec(pd.namespace, key)
+
+	if strict && !documented {
+		return fmt.Errorf("dbml: line %d: unknown directive @%s: %s (strict mode)", pd.line, pd.namespace, key)
+	}
+	if documented && !models.DirectiveLocationAllowed(pd.namespace, key, location) {
+		return fmt.Errorf("dbml: line %d: directive @%s: %s is not valid at %s level", pd.line, pd.namespace, key, location)
+	}
+	if documented && spec.Singleton && models.HasDirective(meta, pd.namespace, key) {
+		return fmt.Errorf("dbml: line %d: duplicate @%s directive %q at %s level", pd.line, pd.namespace, key, location)
+	}
+
+	models.AddDirective(meta, models.Directive{
+		Namespace: pd.namespace,
+		Key:       key,
+		Args:      pd.args,
+		Line:      pd.line,
+	})
+	return nil
+}

pkg/readers/dbml/directives_test.go

@@ -0,0 +1,181 @@
+package dbml
+
+import (
+	"strings"
+	"testing"
+
+	"git.warky.dev/wdevs/relspecgo/pkg/models"
+	"git.warky.dev/wdevs/relspecgo/pkg/readers"
+)
+
+func parse(t *testing.T, strict bool, src string) (*models.Database, error) {
+	t.Helper()
+	r := NewReader(&readers.ReaderOptions{StrictDirectives: strict})
+	return r.parseDBML(src)
+}
+
+func firstTable(t *testing.T, db *models.Database) *models.Table {
+	t.Helper()
+	if len(db.Schemas) == 0 || len(db.Schemas[0].Tables) == 0 {
+		t.Fatal("no table parsed")
+	}
+	return db.Schemas[0].Tables[0]
+}
+
+func TestDirectives_AttachAtEachLocation(t *testing.T) {
+	src := `@postgres: search_path myapp
+
+Table myapp.events {
+  id bigint [pk]
+  created_at timestamp [not null]
+  @postgres(id): identity always
+  @postgres: partition by RANGE (created_at)
+
+  indexes {
+    (created_at) [name: 'idx_events_created']
+    @postgres: with (fillfactor=90)
+  }
+}
+`
+	db, err := parse(t, false, src)
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+
+	if !models.HasDirective(db.Metadata, "postgres", "search_path") {
+		t.Errorf("database-level directive missing: %+v", db.Metadata)
+	}
+
+	tbl := firstTable(t, db)
+	if !models.HasDirective(tbl.Metadata, "postgres", "partition") {
+		t.Errorf("table-level directive missing: %+v", tbl.Metadata)
+	}
+
+	col := tbl.Columns["id"]
+	if col == nil || !models.HasDirective(col.Metadata, "postgres", "identity") {
+		t.Errorf("column-level directive missing")
+	}
+	// Verbatim args preserved.
+	if d := models.DirectivesForNamespace(col.Metadata, "postgres"); len(d) != 1 || d[0].Args != "identity always" {
+		t.Errorf("column directive args = %+v", d)
+	}
+
+	var idx *models.Index
+	for _, i := range tbl.Indexes {
+		idx = i
+	}
+	if idx == nil || !models.HasDirective(idx.Metadata, "postgres", "with") {
+		t.Errorf("index-level directive missing: %+v", idx)
+	}
+}
+
+func TestDirectives_RepeatablePreservedAndOrdered(t *testing.T) {
+	src := `Table s.t {
+  id int [pk]
+  @postgres: with (fillfactor=90)
+  @postgres: with (autovacuum_enabled=off)
+}
+`
+	db, err := parse(t, false, src)
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	tbl := firstTable(t, db)
+	got := models.DirectivesForNamespace(tbl.Metadata, "postgres")
+	if len(got) != 2 {
+		t.Fatalf("got %d directives, want 2", len(got))
+	}
+	if got[0].Args != "with (fillfactor=90)" || got[1].Args != "with (autovacuum_enabled=off)" {
+		t.Errorf("repeatable directives out of order: %+v", got)
+	}
+}
+
+func TestDirectives_SingletonDuplicateErrors(t *testing.T) {
+	src := `Table s.t {
+  id int [pk]
+  @postgres: partition by RANGE (a)
+  @postgres: partition by LIST (b)
+}
+`
+	_, err := parse(t, false, src)
+	if err == nil || !strings.Contains(err.Error(), "duplicate") {
+		t.Fatalf("want duplicate error, got %v", err)
+	}
+	if !strings.Contains(err.Error(), "line 4") {
+		t.Errorf("error not line-numbered: %v", err)
+	}
+}
+
+func TestDirectives_MalformedErrors(t *testing.T) {
+	cases := map[string]string{
+		"no colon":       "@postgres partition by x",
+		"empty args":     "@postgres:",
+		"bad namespace":  "@Postgres: partition by x",
+		"numeric prefix": "@1x: foo",
+	}
+	for name, line := range cases {
+		t.Run(name, func(t *testing.T) {
+			src := "Table s.t {\n  id int [pk]\n  " + line + "\n}\n"
+			_, err := parse(t, false, src)
+			if err == nil {
+				t.Fatalf("want error for %q", line)
+			}
+			if !strings.Contains(err.Error(), "line 3") {
+				t.Errorf("error not line-numbered: %v", err)
+			}
+		})
+	}
+}
+
+func TestDirectives_UnknownPreservedNonStrict(t *testing.T) {
+	src := `Table s.t {
+  id int [pk]
+  @postgres: frobnicate all the things
+  @clickhouse: engine MergeTree
+}
+`
+	db, err := parse(t, false, src)
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	tbl := firstTable(t, db)
+	if !models.HasDirective(tbl.Metadata, "postgres", "frobnicate") {
+		t.Error("unknown postgres key not preserved")
+	}
+	if !models.HasDirective(tbl.Metadata, "clickhouse", "engine") {
+		t.Error("unknown namespace not preserved")
+	}
+}
+
+func TestDirectives_StrictErrors(t *testing.T) {
+	src := `Table s.t {
+  id int [pk]
+  @postgres: frobnicate x
+}
+`
+	_, err := parse(t, true, src)
+	if err == nil || !strings.Contains(err.Error(), "strict mode") {
+		t.Fatalf("want strict-mode error, got %v", err)
+	}
+}
+
+func TestDirectives_UnknownColumnTargetErrors(t *testing.T) {
+	src := `Table s.t {
+  id int [pk]
+  @postgres(missing): identity always
+}
+`
+	_, err := parse(t, false, src)
+	if err == nil || !strings.Contains(err.Error(), "not found") {
+		t.Fatalf("want unknown-column error, got %v", err)
+	}
+}
+
+func TestDirectives_WrongLocationErrors(t *testing.T) {
+	// partition is table-only.
+	src := "@postgres: partition by RANGE (x)\n\nTable s.t {\n  id int [pk]\n}\n"
+	_, err := parse(t, false, src)
+	if err == nil || !strings.Contains(err.Error(), "not valid at database level") {
+		t.Fatalf("want location error, got %v", err)
+	}
+}

pkg/readers/dbml/reader.go

@@ -435,11 +435,14 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 	var inIndexes bool
 	var inTable bool
 	var columnSeq uint
+	var lastIndex *models.Index // most recent index in the current Indexes block
+	lineNo := 0
 
 	tableRegex := regexp.MustCompile(`^Table\s+(.+?)\s*{`)
 	refRegex := regexp.MustCompile(`^Ref:\s+(.+)`)
 
 	for scanner.Scan() {
+		lineNo++
 		line := strings.TrimSpace(scanner.Text())
 
 		// Skip empty lines and comments
@@ -447,6 +450,20 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 			continue
 		}
 
+		// Parse a dialect directive (@postgres:, @sqlite:, …). Handled before
+		// table/column/index parsing so directive lines are never mistaken for
+		// columns.
+		if strings.HasPrefix(line, "@") {
+			pd, err := parseDirectiveLine(line, lineNo)
+			if err != nil {
+				return nil, err
+			}
+			if err := r.attachDirective(pd, db, currentTable, inTable, inIndexes, lastIndex); err != nil {
+				return nil, err
+			}
+			continue
+		}
+
 		// Parse Table definition
 		if matches := tableRegex.FindStringSubmatch(line); matches != nil {
 			tableName := matches[1]
@@ -474,8 +491,10 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 			continue
 		}
 
-		// End of table definition
-		if inTable && line == "}" {
+		// End of table definition. Guarded by !inIndexes so the closing brace
+		// of an `indexes { }` block is not mistaken for the end of the table
+		// (which would drop any table-level content that follows it).
+		if inTable && !inIndexes && line == "}" {
 			if currentTable != nil && currentSchema != "" {
 				schemaMap[currentSchema].Tables = append(schemaMap[currentSchema].Tables, currentTable)
 				currentTable = nil
@@ -488,12 +507,14 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 		// Parse indexes section
 		if inTable && (strings.HasPrefix(line, "Indexes {") || strings.HasPrefix(line, "indexes {")) {
 			inIndexes = true
+			lastIndex = nil
 			continue
 		}
 
 		// End of indexes section
 		if inIndexes && line == "}" {
 			inIndexes = false
+			lastIndex = nil
 			continue
 		}
 
@@ -513,6 +534,7 @@ func (r *Reader) parseDBML(content string) (*models.Database, error) {
 			index := r.parseIndex(line, currentTable.Name, currentSchema)
 			if index != nil {
 				currentTable.Indexes[index.Name] = index
+				lastIndex = index
 			}
 			continue
 		}

pkg/readers/reader.go

@@ -28,6 +28,10 @@ type ReaderOptions struct {
 	// Prisma7 enables Prisma 7-specific handling for Prisma schemas.
 	Prisma7 bool
 
+	// StrictDirectives makes DBML dialect directives (@postgres:, @sqlite:, …)
+	// fail on an unknown namespace or key instead of preserving them silently.
+	StrictDirectives bool
+
 	// Additional options can be added here as needed
 	Metadata map[string]interface{}
 }