ts-mysql-ddl 1.0.0

package/dist/generate-ddl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generate MySQL DDL from TableSchema array.
+ *
+ * Output format matches the style of 001_init.sql:
+ *   - Full CREATE TABLE with IF NOT EXISTS
+ *   - Backtick-quoted identifiers
+ *   - Consistent indentation (2 spaces)
+ *   - Constraints after column definitions
+ *   - ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+ */
+import type { TableSchema } from './table-def';
+/**
+ * Generate DDL for multiple tables.
+ * Returns a single SQL string with CREATE TABLE statements separated by blank lines.
+ */
+export declare function generateDdl(tables: TableSchema[]): string;

package/dist/generate-ddl.js

@@ -0,0 +1,149 @@
+/**
+ * Generate MySQL DDL from TableSchema array.
+ *
+ * Output format matches the style of 001_init.sql:
+ *   - Full CREATE TABLE with IF NOT EXISTS
+ *   - Backtick-quoted identifiers
+ *   - Consistent indentation (2 spaces)
+ *   - Constraints after column definitions
+ *   - ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+ */
+import { columnSqlType } from './column-def.js';
+/** Resolve a ColumnRef or lazy ColumnRef getter */
+function resolveRef(ref) {
+    return typeof ref === 'function' ? ref() : ref;
+}
+/** Resolve column name from a ColumnRef */
+function colName(ref) {
+    return ref._column || '?';
+}
+/** Resolve multiple column refs to names */
+function colNames(refs) {
+    return Array.isArray(refs) ? refs.map(colName) : [colName(refs)];
+}
+/** Safe access to `.default` — only some variants have it */
+function getDefault(def) {
+    if ('default' in def)
+        return def.default;
+    return undefined;
+}
+function isIntColumn(def) {
+    const t = def.type;
+    return t === 'TINYINT' || t === 'SMALLINT' || t === 'INT' || t === 'BIGINT';
+}
+function renderDefault(def) {
+    const val = getDefault(def);
+    if (val === undefined)
+        return '';
+    if (val === 'CURRENT_TIMESTAMP')
+        return ' DEFAULT CURRENT_TIMESTAMP';
+    if (isIntColumn(def)) {
+        return ` DEFAULT ${val}`;
+    }
+    return ` DEFAULT '${val}'`;
+}
+function renderNullable(def) {
+    if ('autoIncrement' in def && def.autoIncrement)
+        return ' NOT NULL';
+    return def.nullable === true ? '' : ' NOT NULL';
+}
+function renderExtra(def) {
+    if ('autoIncrement' in def && def.autoIncrement)
+        return ' AUTO_INCREMENT';
+    return '';
+}
+function renderComment(def) {
+    return def.comment ? ` COMMENT '${def.comment.replace(/'/g, "\\'")}'` : '';
+}
+function renderColumnLine(col) {
+    const { name, def } = col;
+    const sqlType = columnSqlType(def);
+    const nullable = renderNullable(def);
+    const default_ = renderDefault(def);
+    const extra = renderExtra(def);
+    const comment = renderComment(def);
+    return `  \`${name}\` ${sqlType}${nullable}${default_}${extra}${comment}`;
+}
+function renderPrimaryKey(schema, columns) {
+    const pk = schema._schema.primaryKey;
+    if (pk) {
+        const names = Array.isArray(pk) ? pk.map(colName) : [colName(pk)];
+        return `  PRIMARY KEY (\`${names.join('`, `')}\`)`;
+    }
+    // Auto-detect autoIncrement column
+    const autoIncCol = columns.find(c => 'autoIncrement' in c.def && c.def.autoIncrement);
+    if (autoIncCol) {
+        return `  PRIMARY KEY (\`${autoIncCol.name}\`)`;
+    }
+    // Check for column-level primaryKey: true
+    const pkCols = columns.filter(c => 'primaryKey' in c.def && c.def.primaryKey);
+    if (pkCols.length > 0) {
+        return `  PRIMARY KEY (\`${pkCols.map(c => c.name).join('`, `')}\`)`;
+    }
+    return null;
+}
+function renderInlineConstraints(schema, columns) {
+    const lines = [];
+    // UNIQUE constraints declared inline on columns
+    for (const col of columns) {
+        if ('unique' in col.def && col.def.unique) {
+            lines.push(`  UNIQUE KEY \`uk_${schema._schema.name}_${col.name}\` (\`${col.name}\`)`);
+        }
+    }
+    // INDEX constraints declared inline on columns
+    for (const col of columns) {
+        if ('index' in col.def && col.def.index) {
+            lines.push(`  KEY \`idx_${schema._schema.name}_${col.name}\` (\`${col.name}\`)`);
+        }
+    }
+    // Explicit indexes from table.indexes
+    const indexes = schema._schema.indexes;
+    if (indexes) {
+        for (const idx of indexes) {
+            const cols = idx.columns.map(c => `\`${colName(c)}\``).join(', ');
+            const name = idx.name || `idx_${idx.columns.map(c => colName(c)).join('_')}`;
+            const keyword = idx.unique ? 'UNIQUE KEY' : 'KEY';
+            lines.push(`  ${keyword} \`${name}\` (${cols})`);
+        }
+    }
+    return lines;
+}
+// ── Public API ──
+/**
+ * Generate DDL for multiple tables.
+ * Returns a single SQL string with CREATE TABLE statements separated by blank lines.
+ */
+export function generateDdl(tables) {
+    const parts = [];
+    for (const table of tables) {
+        const schema = table._schema;
+        const columns = Object.entries(schema.columns).map(([name, def]) => ({ name, def }));
+        const lines = [];
+        // 1. Column definitions
+        for (const col of columns) {
+            lines.push(renderColumnLine(col));
+        }
+        // 2. Primary key
+        const pkLine = renderPrimaryKey(table, columns);
+        if (pkLine)
+            lines.push(pkLine);
+        // 3. Constraints + indexes
+        const constraintLines = renderInlineConstraints(table, columns);
+        lines.push(...constraintLines);
+        // 4. Foreign keys
+        if (schema.foreignKeys) {
+            for (const [name, fk] of Object.entries(schema.foreignKeys)) {
+                const cols = colNames(fk.columns).map(c => `\`${c}\``).join(', ');
+                const resolved = resolveRef(fk.ref);
+                const onDelete = fk.onDelete ? ` ON DELETE ${fk.onDelete}` : '';
+                lines.push(`  CONSTRAINT \`${name}\` FOREIGN KEY (${cols}) REFERENCES \`${resolved._table}\`(\`${resolved._column}\`)${onDelete}`);
+            }
+        }
+        // 5. Join with commas
+        const body = lines.join(',\n');
+        const comment = schema.comment ? `-- ${schema.comment}\n` : '';
+        const ddl = `${comment}CREATE TABLE IF NOT EXISTS \`${schema.name}\` (\n${body}\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;`;
+        parts.push(ddl);
+    }
+    return parts.join('\n\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { MysqlType } from './mysql-type';
+export type { MysqlType as MysqlTypeT } from './mysql-type';
+export { columnSqlType } from './column-def';
+export type { ColumnDef, EnumShape, IntColumn, DecimalColumn, StringColumn, TextColumn, DateColumn, DateTimeColumn, } from './column-def';
+export { ColumnRef, col } from './column-ref';
+export type { ForeignKey, IndexDef, TableSchema } from './table-def';
+export { defineTable } from './define-table';
+export type { DefineTableInput } from './define-table';
+export { generateDdl } from './generate-ddl';
+export { scanTables } from './scan-tables';
+export { buildSchema } from './build';
+export type { BuildSchemaOptions } from './build';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { MysqlType } from './mysql-type.js';
+export { columnSqlType } from './column-def.js';
+export { ColumnRef, col } from './column-ref.js';
+export { defineTable } from './define-table.js';
+export { generateDdl } from './generate-ddl.js';
+export { scanTables } from './scan-tables.js';
+export { buildSchema } from './build.js';

package/dist/mysql-type.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MySQL data type constants and type guard.
+ *
+ * Usage:
+ *   import { MysqlType } from '@fastify-api/ts-mysql-ddl';
+ *   const col = { type: MysqlType.VARCHAR, length: 100 };
+ */
+export declare const MysqlType: {
+    readonly TINYINT: "TINYINT";
+    readonly SMALLINT: "SMALLINT";
+    readonly INT: "INT";
+    readonly BIGINT: "BIGINT";
+    readonly DECIMAL: "DECIMAL";
+    readonly CHAR: "CHAR";
+    readonly VARCHAR: "VARCHAR";
+    readonly TEXT: "TEXT";
+    readonly DATE: "DATE";
+    readonly DATETIME: "DATETIME";
+    readonly TIMESTAMP: "TIMESTAMP";
+};
+export type MysqlType = (typeof MysqlType)[keyof typeof MysqlType];
+/** Integer type family guard */
+export type IntMysqlType = typeof MysqlType.TINYINT | typeof MysqlType.SMALLINT | typeof MysqlType.INT | typeof MysqlType.BIGINT;
+/** String type family guard */
+export type StringMysqlType = typeof MysqlType.CHAR | typeof MysqlType.VARCHAR;
+/** Date/time type family guard */
+export type DateTimeMysqlType = typeof MysqlType.DATE | typeof MysqlType.DATETIME | typeof MysqlType.TIMESTAMP;
+export declare function isIntType(t: MysqlType): t is IntMysqlType;
+export declare function isStringType(t: MysqlType): t is StringMysqlType;
+export declare function isDateTimeType(t: MysqlType): t is DateTimeMysqlType;

package/dist/mysql-type.js

@@ -0,0 +1,35 @@
+/**
+ * MySQL data type constants and type guard.
+ *
+ * Usage:
+ *   import { MysqlType } from '@fastify-api/ts-mysql-ddl';
+ *   const col = { type: MysqlType.VARCHAR, length: 100 };
+ */
+export const MysqlType = {
+    // Integers
+    TINYINT: 'TINYINT',
+    SMALLINT: 'SMALLINT',
+    INT: 'INT',
+    BIGINT: 'BIGINT',
+    // Decimals
+    DECIMAL: 'DECIMAL',
+    // Strings
+    CHAR: 'CHAR',
+    VARCHAR: 'VARCHAR',
+    // Text
+    TEXT: 'TEXT',
+    // Date / Time
+    DATE: 'DATE',
+    DATETIME: 'DATETIME',
+    TIMESTAMP: 'TIMESTAMP',
+};
+export function isIntType(t) {
+    return t === MysqlType.TINYINT || t === MysqlType.SMALLINT
+        || t === MysqlType.INT || t === MysqlType.BIGINT;
+}
+export function isStringType(t) {
+    return t === MysqlType.CHAR || t === MysqlType.VARCHAR;
+}
+export function isDateTimeType(t) {
+    return t === MysqlType.DATE || t === MysqlType.DATETIME || t === MysqlType.TIMESTAMP;
+}

package/dist/scan-tables.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Auto-discover table definitions from a directory of *.table.ts files.
+ *
+ * Each file exports at minimum `columns` (Record<string, ColumnRef>).
+ * Optional exports: `indexes`, `foreignKeys`, `primaryKey`, `comment`.
+ *
+ * Two-phase initialization ensures FK refs between tables resolve correctly
+ * regardless of file processing order:
+ *   Phase 1 — set _table/_column on all ColumnRefs
+ *   Phase 2 — build full TableSchema with FKs, indexes, etc.
+ *
+ * Usage:
+ *   const tables = await scanTables('./schema');
+ *   const sql = generateDdl(tables);
+ *   console.log(sql);
+ */
+import type { TableSchema } from './table-def';
+/**
+ * Scan a directory for *.table.ts files, import each, and return TableSchema[].
+ * Table name is derived from filename: "order.table.ts" → "order".
+ */
+export declare function scanTables(dir: string): Promise<TableSchema[]>;

package/dist/scan-tables.js

@@ -0,0 +1,59 @@
+/**
+ * Auto-discover table definitions from a directory of *.table.ts files.
+ *
+ * Each file exports at minimum `columns` (Record<string, ColumnRef>).
+ * Optional exports: `indexes`, `foreignKeys`, `primaryKey`, `comment`.
+ *
+ * Two-phase initialization ensures FK refs between tables resolve correctly
+ * regardless of file processing order:
+ *   Phase 1 — set _table/_column on all ColumnRefs
+ *   Phase 2 — build full TableSchema with FKs, indexes, etc.
+ *
+ * Usage:
+ *   const tables = await scanTables('./schema');
+ *   const sql = generateDdl(tables);
+ *   console.log(sql);
+ */
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { defineTable } from './define-table.js';
+/**
+ * Scan a directory for *.table.ts files, import each, and return TableSchema[].
+ * Table name is derived from filename: "order.table.ts" → "order".
+ */
+export async function scanTables(dir) {
+    const absDir = path.resolve(dir);
+    // 1. Discover files
+    const files = readdirSync(absDir)
+        .filter((f) => f.endsWith('.table.ts'))
+        .sort(); // deterministic order
+    if (files.length === 0) {
+        throw new Error(`No *.table.ts files found in ${absDir}`);
+    }
+    // 2. Import all modules
+    const entries = [];
+    for (const file of files) {
+        const modulePath = path.join(absDir, file);
+        const tableName = file.replace(/\.table\.ts$/, '');
+        const mod = await import(pathToFileURL(modulePath).href);
+        if (!mod.columns) {
+            console.warn(`Skipping ${file}: no 'columns' export`);
+            continue;
+        }
+        entries.push({ name: tableName, mod });
+    }
+    // 3. Phase 1 — set column identity on all refs
+    for (const { name, mod } of entries) {
+        for (const [colName, ref] of Object.entries(mod.columns)) {
+            ref._table = name;
+            ref._column = colName;
+        }
+    }
+    // 4. Phase 2 — build full schemas
+    const schemas = [];
+    for (const { name, mod } of entries) {
+        schemas.push(defineTable(name, mod));
+    }
+    return schemas;
+}

package/dist/table-def.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Table definition interfaces.
+ *
+ * Index and FK columns use ColumnRef for compile-time checking:
+ *   indexes: [{ columns: [columns.status, columns.deleted] }]
+ *   foreignKeys: { fk_x: { columns: [columns.mer_id], ref: merchant.columns.id } }
+ */
+import type { ColumnDef } from './column-def';
+import { ColumnRef } from './column-ref';
+export { ColumnRef, col } from './column-ref';
+export interface IndexDef {
+    columns: ColumnRef[];
+    name?: string;
+    unique?: boolean;
+}
+export interface ForeignKey {
+    /** Local column(s) */
+    columns: ColumnRef | ColumnRef[];
+    /** Referenced column — direct ref or lazy for circular deps */
+    ref: ColumnRef | (() => ColumnRef);
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
+}
+export interface TableSchema {
+    /** Internal table definition for DDL generation */
+    readonly _schema: InternalTableDef;
+    /** Column references for FK/index declarations, e.g. merchant.columns.id */
+    readonly columns: Record<string, ColumnRef>;
+}
+/** @internal — not exported directly */
+export interface InternalTableDef {
+    name: string;
+    /** Raw column definitions keyed by column name */
+    columns: Record<string, ColumnDef>;
+    primaryKey?: ColumnRef | ColumnRef[];
+    foreignKeys?: Record<string, ForeignKey>;
+    indexes?: IndexDef[];
+    comment?: string;
+}

package/dist/table-def.js

@@ -0,0 +1,8 @@
+/**
+ * Table definition interfaces.
+ *
+ * Index and FK columns use ColumnRef for compile-time checking:
+ *   indexes: [{ columns: [columns.status, columns.deleted] }]
+ *   foreignKeys: { fk_x: { columns: [columns.mer_id], ref: merchant.columns.id } }
+ */
+export { ColumnRef, col } from './column-ref.js';

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "ts-mysql-ddl",
+  "version": "1.0.0",
+  "description": "TypeScript DSL for MySQL schema definition — define tables in TS, generate DDL SQL",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "ts-mysql-ddl": "bin/ts-mysql-ddl.cjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/fix-imports.mjs",
+    "prepublishOnly": "npm run build",
+    "typecheck": "npx tsc --noEmit",
+    "cli": "npx tsx src/cli.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "tsx": "^4.0.0"
+  },
+  "license": "MIT"
+}

package/src/build.ts

@@ -0,0 +1,65 @@
+/**
+ * Build schema: scan *.table.ts directory → generate DDL → optionally write to file.
+ *
+ * Usage:
+ *   const sql = await buildSchema({ schemaDir: './schema' });
+ *   await buildSchema({ schemaDir: './schema', outFile: './001_init.sql' });
+ */
+
+import { writeFileSync } from 'node:fs';
+import { scanTables } from './scan-tables';
+import { generateDdl } from './generate-ddl';
+import type { TableSchema } from './table-def';
+
+export interface BuildSchemaOptions {
+  /** Directory to scan for *.table.ts files */
+  schemaDir: string;
+  /** Optional output file path — writes generated SQL if provided */
+  outFile?: string;
+}
+
+/** Topological sort by FK dependency — referenced tables come first */
+function sortByDependency(tables: TableSchema[]): TableSchema[] {
+  const byName = new Map(tables.map(t => [t._schema.name, t]));
+  const visited = new Set<string>();
+  const sorted: TableSchema[] = [];
+
+  function visit(name: string) {
+    if (visited.has(name)) return;
+    visited.add(name);
+    const table = byName.get(name);
+    if (!table) return;
+    // Visit FK refs first
+    const fks = table._schema.foreignKeys;
+    if (fks) {
+      for (const fk of Object.values(fks)) {
+        const ref = typeof fk.ref === 'function' ? fk.ref() : fk.ref;
+        if (ref._table && ref._table !== name) {
+          visit(ref._table);
+        }
+      }
+    }
+    sorted.push(table);
+  }
+
+  for (const t of tables) visit(t._schema.name);
+  return sorted;
+}
+
+/**
+ * Scan schema directory, resolve FK dependency order, generate DDL.
+ * Optionally writes result to `outFile`.
+ * Returns the generated SQL string.
+ */
+export async function buildSchema(options: BuildSchemaOptions): Promise<string> {
+  const { schemaDir, outFile } = options;
+  const tables = sortByDependency(await scanTables(schemaDir));
+  const sql = generateDdl(tables);
+
+  if (outFile) {
+    writeFileSync(outFile, sql + '\n', 'utf-8');
+    console.log(`Generated ${tables.length} tables → ${outFile}`);
+  }
+
+  return sql;
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env tsx
+/**
+ * CLI for ts-mysql-ddl: scan *.table.ts → generate DDL → write SQL file.
+ *
+ * Usage:
+ *   ts-mysql-ddl --src ./schema --dest ./001_init.sql
+ */
+
+import { buildSchema } from './build';
+
+function parseArgs(): { src: string; dest: string } {
+  const args = process.argv.slice(2);
+  let src = '';
+  let dest = '';
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--src' && i + 1 < args.length) { src = args[++i]!; }
+    if (arg === '--dest' && i + 1 < args.length) { dest = args[++i]!; }
+  }
+
+  if (!src) throw new Error('Missing required flag: --src <schema_dir>');
+  if (!dest) throw new Error('Missing required flag: --dest <output_file>');
+
+  return { src, dest };
+}
+
+const { src, dest } = parseArgs();
+await buildSchema({ schemaDir: src, outFile: dest });

package/src/column-def.ts

@@ -0,0 +1,112 @@
+/**
+ * Column definition — discriminated union by MysqlType.
+ *
+ * Each type family only allows the parameters that make sense for that type.
+ * Compile-time errors if you try to use `length` on INT or `autoIncrement` on VARCHAR.
+ */
+
+// ── Shared types ──
+
+interface BaseColumn {
+  nullable?: boolean;
+  comment?: string;
+}
+
+/** Any TypeScript enum value — string or numeric */
+export type EnumShape = Record<string, string | number>;
+
+// ── Integer: TINYINT | SMALLINT | INT | BIGINT ──
+
+export interface IntColumn extends BaseColumn {
+  type: typeof import('./mysql-type').MysqlType.TINYINT
+      | typeof import('./mysql-type').MysqlType.SMALLINT
+      | typeof import('./mysql-type').MysqlType.INT
+      | typeof import('./mysql-type').MysqlType.BIGINT;
+  autoIncrement?: true;
+  primaryKey?: true;
+  default?: number;
+  enumRef?: EnumShape;           // real TS enum, e.g. CouponStatus
+  index?: boolean;
+  unique?: boolean;
+}
+
+// ── Decimal: DECIMAL ──
+
+export interface DecimalColumn extends BaseColumn {
+  type: typeof import('./mysql-type').MysqlType.DECIMAL;
+  precision: number;
+  scale: number;
+  default?: string;
+}
+
+// ── String: CHAR | VARCHAR ──
+
+export interface StringColumn extends BaseColumn {
+  type: typeof import('./mysql-type').MysqlType.CHAR
+      | typeof import('./mysql-type').MysqlType.VARCHAR;
+  length: number;
+  enumRef?: EnumShape;           // real TS enum, e.g. CouponStatus
+  primaryKey?: true;
+  default?: string;
+  index?: boolean;
+  unique?: boolean;
+}
+
+// ── Text: TEXT ──
+
+export interface TextColumn extends BaseColumn {
+  type: typeof import('./mysql-type').MysqlType.TEXT;
+}
+
+// ── Date / DateTime ──
+
+export interface DateColumn extends BaseColumn {
+  type: typeof import('./mysql-type').MysqlType.DATE;
+  default?: 'CURRENT_TIMESTAMP';
+}
+
+export interface DateTimeColumn extends BaseColumn {
+  type: typeof import('./mysql-type').MysqlType.DATETIME
+      | typeof import('./mysql-type').MysqlType.TIMESTAMP;
+  default?: 'CURRENT_TIMESTAMP';
+}
+
+// ── Union ──
+
+export type ColumnDef =
+  | IntColumn
+  | DecimalColumn
+  | StringColumn
+  | TextColumn
+  | DateColumn
+  | DateTimeColumn;
+
+// ── Helpers ──
+
+function isIntType(t: string): boolean {
+  return t === 'TINYINT' || t === 'SMALLINT' || t === 'INT' || t === 'BIGINT';
+}
+
+function isStringType(t: string): boolean {
+  return t === 'CHAR' || t === 'VARCHAR';
+}
+
+/** Get the SQL type name with parameters, e.g. "VARCHAR(100)" or "DECIMAL(10,2)" */
+export function columnSqlType(def: ColumnDef): string {
+  const t = def.type;
+
+  if (isIntType(t)) return t;
+
+  if (t === 'DECIMAL') {
+    const d = def as DecimalColumn;
+    return `${t}(${d.precision},${d.scale})`;
+  }
+
+  if (isStringType(t)) {
+    const d = def as StringColumn;
+    return `${t}(${d.length})`;
+  }
+
+  // TEXT, DATE, DATETIME, TIMESTAMP — no params
+  return t;
+}

package/src/column-ref.ts

@@ -0,0 +1,42 @@
+/**
+ * ColumnRef — a column definition that also carries its table/column identity.
+ *
+ * Created via `col()` factory, identity is set by `defineTable()`.
+ * `toString()` enables use in template literals:
+ *   name: `idx_${columns.status}`
+ */
+
+import type { ColumnDef } from './column-def';
+
+export class ColumnRef {
+  /** Underlying column definition (immutable) */
+  readonly def: ColumnDef;
+
+  /** Table name — set by defineTable() */
+  _table: string = '';
+  /** Column name — set by defineTable() */
+  _column: string = '';
+
+  constructor(def: ColumnDef) {
+    this.def = def;
+  }
+
+  /** For template literals: `idx_${col}` → "idx_status" */
+  toString(): string {
+    return this._column || '?';
+  }
+}
+
+/**
+ * Factory to create a ColumnRef from a ColumnDef.
+ *
+ * Usage:
+ *   const columns = {
+ *     id:     col({ type: MysqlType.INT, autoIncrement: true }),
+ *     name:   col({ type: MysqlType.VARCHAR, length: 50 }),
+ *     status: col({ type: MysqlType.VARCHAR, length: 20 }),
+ *   };
+ */
+export function col(def: ColumnDef): ColumnRef {
+  return new ColumnRef(def);
+}