@sqldoc/templates 0.0.1

package/src/rust-structs/index.ts

@@ -0,0 +1,152 @@
+import { defineTemplate } from '@sqldoc/ns-codegen'
+import { activeTables, enrichRealm } from '../helpers/enrich.ts'
+import { toPascalCase } from '../helpers/naming.ts'
+import { pgToRust } from '../types/pg-to-rust.ts'
+
+export default defineTemplate({
+  name: 'Rust Structs',
+  description: 'Generate Rust structs with serde derives from SQL schema',
+  language: 'rust',
+
+  generate(ctx) {
+    const schema = enrichRealm(ctx)
+    const allImports = new Set<string>()
+    allImports.add('serde::{Serialize, Deserialize}')
+    const structs: string[] = []
+
+    // Enums
+    for (const e of schema.enums) {
+      const enumName = toPascalCase(e.name)
+      const variants = e.values.map((v) => {
+        const variantName = toPascalCase(v)
+        return `    #[serde(rename = "${v}")]\n    ${variantName},`
+      })
+      structs.push(`#[derive(Debug, Clone, Serialize, Deserialize)]\npub enum ${enumName} {\n${variants.join('\n')}\n}`)
+    }
+
+    // Composite types as structs
+    const composites = new Map<string, Array<{ name: string; type: string }>>()
+    for (const table of schema.tables) {
+      for (const col of table.columns) {
+        if (col.category === 'composite' && col.compositeFields?.length && !composites.has(col.pgType)) {
+          composites.set(col.pgType, col.compositeFields)
+        }
+      }
+    }
+    for (const [name, fields] of composites) {
+      const structName = toPascalCase(name)
+      const rustFields = fields.map((f) => {
+        const mapped = pgToRust(f.type, false)
+        for (const imp of mapped.imports) allImports.add(imp)
+        return `    pub ${f.name}: ${mapped.type},`
+      })
+      structs.push(
+        `#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ${structName} {\n${rustFields.join('\n')}\n}`,
+      )
+    }
+
+    for (const table of activeTables(schema)) {
+      const fields: string[] = []
+      for (const col of table.columns) {
+        let rustType: string
+        if (col.typeOverride) {
+          rustType = col.nullable ? `Option<${col.typeOverride}>` : col.typeOverride
+        } else if (col.category === 'enum' && col.enumValues?.length) {
+          const enumType = toPascalCase(col.pgType)
+          rustType = col.nullable ? `Option<${enumType}>` : enumType
+        } else if (col.category === 'composite' && col.compositeFields?.length) {
+          const compositeType = toPascalCase(col.pgType)
+          rustType = col.nullable ? `Option<${compositeType}>` : compositeType
+        } else {
+          const mapped = pgToRust(col.pgType, col.nullable, col.category)
+          rustType = mapped.type
+          for (const imp of mapped.imports) allImports.add(imp)
+        }
+
+        // snake_case is the Rust convention, which matches PostgreSQL column names
+        const fieldName = col.name
+        fields.push(`    pub ${fieldName}: ${rustType},`)
+      }
+
+      structs.push('#[derive(Debug, Clone, Serialize, Deserialize)]')
+      structs.push(`pub struct ${table.pascalName} {`)
+      structs.push(fields.join('\n'))
+      structs.push('}')
+    }
+
+    // Views (read-only)
+    for (const view of schema.views.filter((v) => !v.skipped)) {
+      const fields: string[] = []
+      for (const col of view.columns) {
+        let rustType: string
+        if (col.typeOverride) {
+          rustType = col.nullable ? `Option<${col.typeOverride}>` : col.typeOverride
+        } else if (col.category === 'enum' && col.enumValues?.length) {
+          const enumType = toPascalCase(col.pgType)
+          rustType = col.nullable ? `Option<${enumType}>` : enumType
+        } else if (col.category === 'composite' && col.compositeFields?.length) {
+          const compositeType = toPascalCase(col.pgType)
+          rustType = col.nullable ? `Option<${compositeType}>` : compositeType
+        } else {
+          const mapped = pgToRust(col.pgType, col.nullable, col.category)
+          rustType = mapped.type
+          for (const imp of mapped.imports) allImports.add(imp)
+        }
+
+        fields.push(`    pub ${col.name}: ${rustType},`)
+      }
+
+      structs.push(`/// Read-only (from view)`)
+      structs.push('#[derive(Debug, Clone, Serialize, Deserialize)]')
+      structs.push(`pub struct ${view.pascalName} {`)
+      structs.push(fields.join('\n'))
+      structs.push('}')
+    }
+
+    // Functions (skip trigger functions)
+    for (const fn of schema.functions) {
+      const retRaw = fn.returnType?.type?.toLowerCase() ?? ''
+      if (retRaw === 'trigger') continue
+
+      let retType: string
+      if (retRaw.startsWith('setof ')) {
+        const tableName = retRaw.replace('setof ', '')
+        const table = schema.tables.find((t) => t.name === tableName)
+        retType = table ? `Vec<${table.pascalName}>` : `Vec<${toPascalCase(tableName)}>`
+      } else if (fn.returnType) {
+        const mapped = pgToRust(fn.returnType.type, false, fn.returnType.category)
+        retType = mapped.type
+        for (const imp of mapped.imports) allImports.add(imp)
+      } else {
+        retType = '()'
+      }
+
+      const argTypes = fn.args
+        .filter((a) => !a.name?.startsWith('_') && (a as any).mode !== 'OUT')
+        .map((a) => {
+          const mapped = pgToRust(a.type, false, a.category)
+          for (const imp of mapped.imports) allImports.add(imp)
+          return mapped.type
+        })
+
+      structs.push(`pub type ${fn.pascalName} = fn(${argTypes.join(', ')}) -> ${retType};`)
+    }
+
+    if (structs.length === 0) {
+      return { files: [] }
+    }
+
+    const sortedImports = [...allImports].sort()
+    const useLines = sortedImports.map((imp) => `use ${imp};`)
+
+    const parts: string[] = []
+    parts.push(useLines.join('\n'))
+    parts.push('')
+    parts.push(structs.join('\n\n'))
+    parts.push('')
+
+    return {
+      files: [{ path: 'models.rs', content: parts.join('\n') }],
+    }
+  },
+})

package/src/rust-structs/test/.gitignore

@@ -0,0 +1,6 @@
+# Generated by codegen — only Dockerfile and test scripts are tracked
+*
+!.gitignore
+!Dockerfile
+!test.*
+!Test.*

package/src/rust-structs/test/Dockerfile

@@ -0,0 +1,22 @@
+FROM rust:1.85-slim
+RUN apt-get update && apt-get install -y pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+RUN cargo init --name typecheck .
+RUN cat >> Cargo.toml <<'TOML'
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+chrono = { version = "0.4", features = ["serde"] }
+uuid = { version = "1", features = ["serde"] }
+bigdecimal = { version = "0.4", features = ["serde"] }
+tokio = { version = "1", features = ["full"] }
+tokio-postgres = "0.7"
+TOML
+RUN rm src/main.rs
+COPY models.rs src/models.rs
+COPY test.rs src/main.rs
+# Prepend mod declaration to main.rs
+RUN sed -i '1s/^/mod models;\n/' src/main.rs
+# Step 1: compile (typechecks models + test)
+RUN cargo build --release
+# Step 2: run integration test against real DB
+CMD ["./target/release/typecheck"]

package/src/rust-structs/test/test.rs

@@ -0,0 +1,82 @@
+// Integration test for @sqldoc/templates/rust-structs
+// Connects to real Postgres, verifies generated structs work with actual data.
+//
+// Note: `mod models;` is prepended by the Dockerfile.
+
+use models::{Users, Posts};
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+static FAILED: AtomicUsize = AtomicUsize::new(0);
+
+fn assert_eq_val<T: PartialEq + std::fmt::Debug>(actual: T, expected: T, msg: &str) {
+    if actual != expected {
+        eprintln!("FAIL: {} (got {:?}, expected {:?})", msg, actual, expected);
+        FAILED.fetch_add(1, Ordering::SeqCst);
+    } else {
+        println!("  ok: {}", msg);
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let db_url = std::env::var("DATABASE_URL").expect("DATABASE_URL not set");
+
+    let (client, connection) = tokio_postgres::connect(&db_url, tokio_postgres::NoTls).await?;
+
+    tokio::spawn(async move {
+        if let Err(e) = connection.await {
+            eprintln!("connection error: {}", e);
+        }
+    });
+
+    println!("--- rust-structs integration test ---");
+
+    // 1. Query user and populate generated struct
+    let row = client
+        .query_one("SELECT id, email, name, age, is_active FROM users WHERE id = 1", &[])
+        .await?;
+    let user = Users {
+        id: row.get("id"),
+        email: row.get("email"),
+        name: row.get("name"),
+        age: row.get("age"),
+        is_active: row.get("is_active"),
+        metadata: None,
+        address: None,
+        created_at: chrono::Utc::now(),
+        tags: None,
+        avatar: None,
+        balance: None,
+        external_id: None,
+    };
+    assert_eq_val(user.email.as_str(), "test@example.com", "user.email matches");
+    assert_eq_val(user.name, Some("Test User".to_string()), "user.name matches");
+    assert_eq_val(user.age, Some(30), "user.age matches");
+    assert_eq_val(user.is_active, true, "user.is_active matches");
+
+    // 2. Query post and populate generated struct
+    let row = client
+        .query_one("SELECT id, user_id, title, body, view_count FROM posts WHERE id = 1", &[])
+        .await?;
+    let post = Posts {
+        id: row.get("id"),
+        user_id: row.get("user_id"),
+        title: row.get("title"),
+        body: row.get("body"),
+        published_at: None,
+        view_count: row.get("view_count"),
+        rating: None,
+    };
+    assert_eq_val(post.title.as_str(), "Hello World", "post.title matches");
+    assert_eq_val(post.user_id, 1i64, "post.user_id matches");
+    assert_eq_val(post.view_count, 42i32, "post.view_count matches");
+
+    let fail_count = FAILED.load(Ordering::SeqCst);
+    if fail_count > 0 {
+        eprintln!("\n{} assertion(s) failed", fail_count);
+        std::process::exit(1);
+    }
+    println!("\nAll assertions passed!");
+    Ok(())
+}

package/src/sqlalchemy/index.ts

@@ -0,0 +1,258 @@
+import { defineTemplate } from '@sqldoc/ns-codegen'
+import { activeTables, enrichRealm } from '../helpers/enrich.ts'
+import { toPascalCase, toScreamingSnake } from '../helpers/naming.ts'
+import { pgToPython } from '../types/pg-to-python.ts'
+
+/** Map PostgreSQL types to SQLAlchemy Column types */
+const PG_TO_SA: Record<string, string> = {
+  smallint: 'SmallInteger',
+  int2: 'SmallInteger',
+  integer: 'Integer',
+  int: 'Integer',
+  int4: 'Integer',
+  bigint: 'BigInteger',
+  int8: 'BigInteger',
+  serial: 'Integer',
+  serial4: 'Integer',
+  bigserial: 'BigInteger',
+  serial8: 'BigInteger',
+  smallserial: 'SmallInteger',
+  serial2: 'SmallInteger',
+  real: 'Float',
+  float4: 'Float',
+  'double precision': 'Float',
+  float8: 'Float',
+  numeric: 'Numeric',
+  decimal: 'Numeric',
+  money: 'Numeric',
+  text: 'Text',
+  varchar: 'String',
+  'character varying': 'String',
+  char: 'String',
+  character: 'String',
+  name: 'String',
+  citext: 'Text',
+  boolean: 'Boolean',
+  bool: 'Boolean',
+  timestamp: 'DateTime',
+  'timestamp without time zone': 'DateTime',
+  timestamptz: 'DateTime',
+  'timestamp with time zone': 'DateTime',
+  date: 'Date',
+  time: 'Time',
+  'time without time zone': 'Time',
+  timetz: 'Time',
+  'time with time zone': 'Time',
+  interval: 'Interval',
+  bytea: 'LargeBinary',
+  json: 'JSON',
+  jsonb: 'JSON',
+  uuid: 'String',
+  inet: 'String',
+  cidr: 'String',
+  macaddr: 'String',
+  macaddr8: 'String',
+}
+
+/** Python imports needed for specific types (used by composite dataclasses) */
+const TYPE_IMPORTS: Record<string, string> = {
+  datetime: 'from datetime import datetime',
+  date: 'from datetime import date',
+  time: 'from datetime import time',
+  timedelta: 'from datetime import timedelta',
+  Decimal: 'from decimal import Decimal',
+  UUID: 'from uuid import UUID',
+  Any: 'from typing import Any',
+}
+
+/** Attribute names reserved by SQLAlchemy's declarative base */
+const SA_RESERVED = new Set(['metadata', 'registry', 'query', 'query_class'])
+
+export default defineTemplate({
+  name: 'SQLAlchemy Models',
+  description: 'Generate SQLAlchemy ORM model classes with Column definitions from SQL schema',
+  language: 'python',
+
+  generate(ctx) {
+    const schema = enrichRealm(ctx)
+    const saTypes = new Set<string>()
+    const needsForeignKey = { value: false }
+    const needsARRAY = { value: false }
+    const needsEnum = { value: false }
+    const needsDataclass = { value: false }
+    const extraImports = new Set<string>()
+    const modelBlocks: string[] = []
+    const enumBlocks: string[] = []
+    const compositeBlocks: string[] = []
+
+    // Enums
+    for (const e of schema.enums) {
+      needsEnum.value = true
+      const className = toPascalCase(e.name)
+      const members = e.values.map((v) => `    ${toScreamingSnake(v)} = "${v}"`).join('\n')
+      enumBlocks.push(`class ${className}(str, enum.Enum):\n${members}`)
+    }
+
+    // Composite types (collected from columns, rendered as dataclasses)
+    const composites = new Map<string, Array<{ name: string; type: string }>>()
+    for (const table of schema.tables) {
+      for (const col of table.columns) {
+        if (col.category === 'composite' && col.compositeFields?.length && !composites.has(col.pgType)) {
+          composites.set(col.pgType, col.compositeFields)
+        }
+      }
+    }
+    for (const [name, fields] of composites) {
+      needsDataclass.value = true
+      const typeName = toPascalCase(name)
+      const fieldLines: string[] = []
+      for (const f of fields) {
+        const pyType = pgToPython(f.type, false)
+        collectTypeImports(pyType, extraImports)
+        fieldLines.push(`    ${f.name}: ${pyType}`)
+      }
+      compositeBlocks.push(`@dataclass\nclass ${typeName}:\n${fieldLines.join('\n')}`)
+    }
+
+    for (const table of activeTables(schema)) {
+      const lines: string[] = []
+      lines.push(`class ${table.pascalName}(Base):`)
+      lines.push(`    __tablename__ = '${table.name}'`)
+      lines.push('')
+
+      for (const col of table.columns) {
+        let saType: string
+
+        if (col.typeOverride) {
+          saType = col.typeOverride
+        } else if (col.category === 'enum' && col.enumValues?.length) {
+          saType = `Enum(${toPascalCase(col.pgType)})`
+          saTypes.add('Enum')
+        } else {
+          saType = mapToSAType(col.pgType, saTypes, needsARRAY)
+        }
+
+        const columnArgs: string[] = [saType]
+
+        // Foreign key
+        if (col.foreignKey) {
+          columnArgs.push(`ForeignKey('${col.foreignKey.table}.${col.foreignKey.column}')`)
+          needsForeignKey.value = true
+        }
+
+        // Column kwargs
+        const kwargs: string[] = []
+        if (col.isPrimaryKey) kwargs.push('primary_key=True')
+        if (!col.nullable && !col.isPrimaryKey) kwargs.push('nullable=False')
+
+        const allArgs = [...columnArgs, ...kwargs].join(', ')
+        const attr = SA_RESERVED.has(col.name) ? `${col.name}_` : col.name
+        const colName = attr !== col.name ? `'${col.name}', ` : ''
+        lines.push(`    ${attr} = Column(${colName}${allArgs})`)
+      }
+
+      modelBlocks.push(lines.join('\n'))
+    }
+
+    // Views (read-only, plain Table objects — no ORM PK requirement)
+    const needsTable = { value: false }
+    const viewBlocks: string[] = []
+    for (const view of schema.views.filter((v) => !v.skipped)) {
+      needsTable.value = true
+      const colDefs: string[] = []
+      for (const col of view.columns) {
+        let saType: string
+        if (col.typeOverride) {
+          saType = col.typeOverride
+        } else if (col.category === 'enum' && col.enumValues?.length) {
+          saType = `Enum(${toPascalCase(col.pgType)})`
+          saTypes.add('Enum')
+        } else {
+          saType = mapToSAType(col.pgType, saTypes, needsARRAY)
+        }
+        colDefs.push(`    Column('${col.name}', ${saType}),`)
+      }
+      viewBlocks.push(`${view.name} = Table(\n    '${view.name}',\n    Base.metadata,\n${colDefs.join('\n')}\n)`)
+    }
+
+    // Collect needed SA type imports
+    const saImportTypes = ['Column', ...saTypes].sort()
+    if (needsForeignKey.value) saImportTypes.push('ForeignKey')
+    if (needsARRAY.value) saImportTypes.push('ARRAY')
+    if (needsTable.value) saImportTypes.push('Table')
+
+    const importLines: string[] = [
+      `from sqlalchemy import ${saImportTypes.join(', ')}`,
+      'from sqlalchemy.orm import declarative_base',
+    ]
+    if (needsDataclass.value) {
+      importLines.push('from dataclasses import dataclass')
+    }
+    if (needsEnum.value) {
+      importLines.push('import enum')
+    }
+    for (const imp of [...extraImports].sort()) {
+      importLines.push(imp)
+    }
+
+    const preModelBlocks = [...enumBlocks, ...compositeBlocks]
+
+    const content = `# Generated by @sqldoc/templates/sqlalchemy -- DO NOT EDIT
+
+${importLines.join('\n')}
+
+Base = declarative_base()
+
+${preModelBlocks.length > 0 ? `\n${preModelBlocks.join('\n\n\n')}\n\n` : ''}
+${modelBlocks.join('\n\n\n')}
+${viewBlocks.length > 0 ? `\n\n# Views\n${viewBlocks.join('\n\n\n')}\n` : ''}
+`
+
+    return {
+      files: [{ path: 'models.py', content }],
+    }
+  },
+})
+
+function collectTypeImports(pyType: string, imports: Set<string>): void {
+  const match = pyType.match(/^Optional\[(.+)\]$/)
+  const baseType = match ? match[1] : pyType
+  const listMatch = baseType.match(/^list\[(.+)\]$/)
+  const innerType = listMatch ? listMatch[1] : baseType
+
+  if (TYPE_IMPORTS[innerType]) {
+    imports.add(TYPE_IMPORTS[innerType])
+  }
+}
+
+function mapToSAType(pgType: string, saTypes: Set<string>, needsARRAY: { value: boolean }): string {
+  const normalized = pgType.toLowerCase().trim()
+
+  // Handle arrays
+  if (normalized.endsWith('[]') || normalized.startsWith('_')) {
+    const base = normalized.endsWith('[]') ? normalized.slice(0, -2) : normalized.slice(1)
+    const innerType = mapToSAType(base, saTypes, needsARRAY)
+    needsARRAY.value = true
+    return `ARRAY(${innerType})`
+  }
+
+  // Handle varchar(n)
+  const lengthMatch = normalized.match(/^(?:varchar|character varying|char|character)\((\d+)\)$/)
+  if (lengthMatch) {
+    saTypes.add('String')
+    return `String(${lengthMatch[1]})`
+  }
+
+  // Handle numeric(p,s)
+  const numericMatch = normalized.match(/^(?:numeric|decimal)\((\d+),\s*(\d+)\)$/)
+  if (numericMatch) {
+    saTypes.add('Numeric')
+    return `Numeric(${numericMatch[1]}, ${numericMatch[2]})`
+  }
+
+  // Strip remaining length specifiers for lookup
+  const baseType = normalized.replace(/\(\d+(?:,\s*\d+)?\)/, '').trim()
+  const saType = PG_TO_SA[baseType] ?? 'String'
+  saTypes.add(saType)
+  return saType
+}

package/src/sqlalchemy/test/.gitignore

@@ -0,0 +1,6 @@
+# Generated by codegen — only Dockerfile and test scripts are tracked
+*
+!.gitignore
+!Dockerfile
+!test.*
+!Test.*

package/src/sqlalchemy/test/Dockerfile

@@ -0,0 +1,8 @@
+FROM python:3.13-slim
+WORKDIR /app
+COPY . .
+RUN pip install sqlalchemy psycopg2-binary
+# Step 1: syntax check the generated models
+RUN python -m py_compile models.py
+# Step 2: run integration test against real DB
+CMD ["python", "test.py"]

package/src/sqlalchemy/test/test.py

@@ -0,0 +1,61 @@
+"""
+Integration test for @sqldoc/templates/sqlalchemy
+Connects to real Postgres, verifies generated SQLAlchemy models work with actual data.
+"""
+import os
+import sys
+
+from sqlalchemy import create_engine, select
+from sqlalchemy.orm import Session
+
+import models
+
+DATABASE_URL = os.environ.get("DATABASE_URL")
+if not DATABASE_URL:
+    print("DATABASE_URL not set", file=sys.stderr)
+    sys.exit(1)
+
+failed = 0
+
+
+def assert_eq(actual, expected, msg):
+    global failed
+    if actual != expected:
+        print(f"FAIL: {msg} (got {actual!r}, expected {expected!r})", file=sys.stderr)
+        failed += 1
+    else:
+        print(f"  ok: {msg}")
+
+
+def main():
+    global failed
+    engine = create_engine(DATABASE_URL)
+
+    print("--- sqlalchemy integration test ---")
+
+    with Session(engine) as session:
+        # 1. Query known seeded user via ORM model
+        user = session.query(models.Users).filter_by(id=1).one()
+        assert_eq(user.email, "test@example.com", "user email matches")
+        assert_eq(user.name, "Test User", "user name matches")
+        assert_eq(user.age, 30, "user age matches")
+        assert_eq(user.is_active, True, "user is_active matches")
+
+        # 2. Query known seeded post via ORM model
+        post = session.query(models.Posts).filter_by(id=1).one()
+        assert_eq(post.title, "Hello World", "post title matches")
+
+        # 3. Query view via Table object
+        rows = session.execute(select(models.active_users)).fetchall()
+        assert_eq(len(rows) >= 1, True, "active_users view returns rows")
+        row = rows[0]
+        assert_eq(row.email, "test@example.com", "view email matches")
+
+    if failed > 0:
+        print(f"\n{failed} assertion(s) failed", file=sys.stderr)
+        sys.exit(1)
+    print("\nAll assertions passed!")
+
+
+if __name__ == "__main__":
+    main()