@zyno-io/dk-server-foundation 26.412.2137 → 26.509.2227

package/src/database/migration/create/ddl-generator.ts

@@ -1,10 +1,28 @@
-import { quoteId } from '../../dialect';
+import { Grammar, MySQLGrammar, PostgresGrammar } from '../../schema';
 import { ColumnModification, ColumnSchema, Dialect, ForeignKeySchema, IndexSchema, SchemaDiff, TableDiff, TableSchema } from './schema-model';
 
-const VALID_FK_ACTIONS = new Set(['RESTRICT', 'CASCADE', 'SET NULL', 'SET DEFAULT', 'NO ACTION']);
-
 export const COMMENT_PREFIX = '\x00comment:';
 
+// --- Grammar delegation ---
+//
+// SQL emission lives in src/database/schema/grammar/. This module owns the high-level
+// diff orchestration (statement ordering, deferred FKs, PG enum dedup, MySQL column
+// reordering, etc.). The thin helpers below delegate to dialect-specific Grammars.
+
+const grammarCache = new Map<string, Grammar>();
+function getGrammar(dialect: Dialect, pgSchema?: string): Grammar {
+    const key = `${dialect}:${pgSchema ?? 'public'}`;
+    let g = grammarCache.get(key);
+    if (!g) {
+        g = dialect === 'mysql' ? new MySQLGrammar(pgSchema ?? 'public') : new PostgresGrammar(pgSchema ?? 'public');
+        grammarCache.set(key, g);
+    }
+    return g;
+}
+function getPgGrammar(pgSchema?: string): PostgresGrammar {
+    return getGrammar('postgres', pgSchema) as PostgresGrammar;
+}
+
 export function generateDDL(diff: SchemaDiff): string[] {
     const statements: string[] = [];
     const { dialect, pgSchema } = diff;
@@ -485,216 +503,33 @@ function generatePostgresTableDDL(diff: TableDiff, pgSchema?: string, globalEnum
 // --- Shared helpers ---
 
 function createTable(table: TableSchema, dialect: Dialect, pgSchema?: string): string {
-    const lines: string[] = [];
-    const pkCols = table.columns.filter(c => c.isPrimaryKey).map(c => c.name);
-
-    for (const col of table.columns) {
-        if (dialect === 'mysql') {
-            lines.push(`    ${mysqlColumnDef(col)}`);
-        } else {
-            lines.push(`    ${pgColumnDef(col, pgSchema)}`);
-        }
-    }
-
-    if (pkCols.length > 0) {
-        const quoted = pkCols.map(c => q(dialect, c)).join(', ');
-        lines.push(`    PRIMARY KEY (${quoted})`);
-    }
-
-    return `CREATE TABLE ${qTable(dialect, table.name, pgSchema)} (\n${lines.join(',\n')}\n)`;
+    return getGrammar(dialect, pgSchema).createTable(table);
 }
 
 function createIndex(tableName: string, idx: IndexSchema, dialect: Dialect, pgSchema?: string): string {
-    const unique = idx.unique ? 'UNIQUE ' : '';
-    const spatial = idx.spatial && dialect === 'mysql' ? 'SPATIAL ' : '';
-    const cols = idx.columns.map(c => q(dialect, c)).join(', ');
-    return `CREATE ${spatial}${unique}INDEX ${q(dialect, idx.name)} ON ${qTable(dialect, tableName, pgSchema)} (${cols})`;
+    return getGrammar(dialect, pgSchema).createIndex(tableName, idx);
 }
 
 function addForeignKey(tableName: string, fk: ForeignKeySchema, dialect: Dialect, pgSchema?: string): string {
-    const cols = fk.columns.map(c => q(dialect, c)).join(', ');
-    const refCols = fk.referencedColumns.map(c => q(dialect, c)).join(', ');
-    const onDelete = validateFkAction(fk.onDelete, dialect);
-    const onUpdate = validateFkAction(fk.onUpdate, dialect);
-    return (
-        `ALTER TABLE ${qTable(dialect, tableName, pgSchema)} ADD CONSTRAINT ${q(dialect, fk.name)} ` +
-        `FOREIGN KEY (${cols}) REFERENCES ${qTable(dialect, fk.referencedTable, pgSchema)} (${refCols}) ` +
-        `ON DELETE ${onDelete} ON UPDATE ${onUpdate}`
-    );
-}
-
-function validateFkAction(action: string, dialect: Dialect): string {
-    const upper = action.toUpperCase();
-    if (!VALID_FK_ACTIONS.has(upper)) {
-        throw new Error(`Invalid foreign key action: '${action}'`);
-    }
-    if (upper === 'SET DEFAULT' && dialect === 'mysql') {
-        throw new Error(`Foreign key action 'SET DEFAULT' is not supported by MySQL/InnoDB`);
-    }
-    return upper;
+    return getGrammar(dialect, pgSchema).addForeignKey(tableName, fk);
 }
 
 function createEnumType(typeName: string, values: string[], pgSchema?: string): string[] {
-    const qualifiedName = qType(typeName, pgSchema);
-    const vals = values.map(v => `'${escapeStr(v)}'`).join(', ');
-    const schemaFilter =
-        pgSchema && pgSchema !== 'public' ? ` AND typnamespace = (SELECT oid FROM pg_namespace WHERE nspname = '${escapeStr(pgSchema)}')` : '';
-    return [
-        [
-            `DO $$ BEGIN`,
-            `IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = '${escapeStr(typeName)}'${schemaFilter}) THEN`,
-            `    CREATE TYPE ${qualifiedName} AS ENUM (${vals});`,
-            `END IF;`,
-            `END $$`
-        ].join('\n'),
-        `CREATE CAST (text AS ${qualifiedName}) WITH INOUT AS IMPLICIT`
-    ];
+    return getPgGrammar(pgSchema).createEnumType(typeName, values);
 }
 
-// --- MySQL column definition ---
+// --- Column definition (delegated to Grammar) ---
 
 function mysqlColumnDef(col: ColumnSchema): string {
-    let def = `${q('mysql', col.name)} ${mysqlTypeDef(col)}`;
-
-    if (col.unsigned) def += ' UNSIGNED';
-    if (!col.nullable) def += ' NOT NULL';
-    if (col.autoIncrement) def += ' AUTO_INCREMENT';
-
-    if (col.defaultExpression) {
-        def += ` DEFAULT ${col.defaultExpression}`;
-    } else if (col.defaultValue !== undefined) {
-        def += ` DEFAULT '${escapeStr(String(col.defaultValue), 'mysql')}'`;
-    }
-
-    if (col.onUpdateExpression) {
-        def += ` ON UPDATE ${col.onUpdateExpression}`;
-    }
-
-    return def;
-}
-
-function mysqlTypeDef(col: ColumnSchema): string {
-    switch (col.type) {
-        case 'varchar':
-            return `VARCHAR(${col.size || 255})`;
-        case 'char':
-            return `CHAR(${col.size || 1})`;
-        case 'tinyint':
-            return col.size === 1 ? 'TINYINT(1)' : 'TINYINT';
-        case 'smallint':
-            return 'SMALLINT';
-        case 'int':
-            return 'INT';
-        case 'bigint':
-            return 'BIGINT';
-        case 'float':
-            return 'FLOAT';
-        case 'double':
-            return 'DOUBLE';
-        case 'decimal':
-            if (col.size === undefined) return 'DECIMAL';
-            return col.scale !== undefined ? `DECIMAL(${col.size},${col.scale})` : `DECIMAL(${col.size})`;
-        case 'boolean':
-            return 'TINYINT(1)';
-        case 'date':
-            return 'DATE';
-        case 'datetime':
-            return 'DATETIME';
-        case 'timestamp':
-            return 'TIMESTAMP';
-        case 'text':
-            return 'TEXT';
-        case 'binary':
-            return `BINARY(${col.size || 16})`;
-        case 'blob':
-            return 'BLOB';
-        case 'json':
-            return 'JSON';
-        case 'point':
-            return 'POINT';
-        case 'enum':
-            if (col.enumValues) {
-                const vals = col.enumValues.map(v => `'${escapeStr(v, 'mysql')}'`).join(',');
-                return `ENUM(${vals})`;
-            }
-            return 'VARCHAR(255)';
-        default:
-            return col.type.toUpperCase();
-    }
+    return getGrammar('mysql').columnDef(col);
 }
 
-// --- PostgreSQL column definition ---
-
 function pgColumnDef(col: ColumnSchema, pgSchema?: string): string {
-    let typeDef: string;
-    if (col.autoIncrement) {
-        // Use SERIAL/BIGSERIAL for auto-increment
-        typeDef = col.type === 'bigint' ? 'BIGSERIAL' : 'SERIAL';
-    } else {
-        typeDef = pgTypeDef(col, pgSchema);
-    }
-
-    let def = `${q('postgres', col.name)} ${typeDef}`;
-
-    if (!col.nullable && !col.autoIncrement) def += ' NOT NULL';
-
-    if (!col.autoIncrement) {
-        if (col.defaultExpression) {
-            def += ` DEFAULT ${col.defaultExpression}`;
-        } else if (col.defaultValue !== undefined) {
-            def += ` DEFAULT '${escapeStr(String(col.defaultValue))}'`;
-        }
-    }
-
-    return def;
+    return getGrammar('postgres', pgSchema).columnDef(col);
 }
 
 function pgTypeDef(col: ColumnSchema, pgSchema?: string): string {
-    switch (col.type) {
-        case 'varchar':
-            return col.size ? `VARCHAR(${col.size})` : 'VARCHAR';
-        case 'char':
-            return `CHAR(${col.size || 1})`;
-        case 'smallint':
-            return 'SMALLINT';
-        case 'int':
-        case 'integer':
-            return 'INTEGER';
-        case 'bigint':
-            return 'BIGINT';
-        case 'real':
-        case 'float':
-            return 'REAL';
-        case 'double precision':
-        case 'double':
-            return 'DOUBLE PRECISION';
-        case 'decimal':
-        case 'numeric':
-            if (col.size === undefined) return 'NUMERIC';
-            return col.scale !== undefined ? `NUMERIC(${col.size},${col.scale})` : `NUMERIC(${col.size})`;
-        case 'boolean':
-            return 'BOOLEAN';
-        case 'date':
-            return 'DATE';
-        case 'timestamp':
-            return 'TIMESTAMP';
-        case 'timestamptz':
-            return 'TIMESTAMPTZ';
-        case 'text':
-            return 'TEXT';
-        case 'bytea':
-            return 'BYTEA';
-        case 'json':
-            return 'JSON';
-        case 'jsonb':
-            return 'JSONB';
-        case 'uuid':
-            return 'UUID';
-        case 'enum':
-            return col.enumTypeName ? qType(col.enumTypeName, pgSchema) : 'TEXT';
-        default:
-            return col.type.toUpperCase();
-    }
+    return getPgGrammar(pgSchema).columnType(col);
 }
 
 // --- AFTER clause helpers (MySQL) ---
@@ -737,35 +572,23 @@ function findAfterClauseForExisting(colName: string, diff: TableDiff, dialect: D
 }
 
 function q(dialect: Dialect, name: string): string {
-    return quoteId(dialect, name);
+    return getGrammar(dialect).quote(name);
 }
 
 function qTable(dialect: Dialect, name: string, pgSchema?: string): string {
-    if (dialect === 'postgres' && pgSchema && pgSchema !== 'public') {
-        return `${quoteId(dialect, pgSchema)}.${quoteId(dialect, name)}`;
-    }
-    return quoteId(dialect, name);
+    return getGrammar(dialect, pgSchema).qualifiedTable(name);
 }
 
 function qType(typeName: string, pgSchema?: string): string {
-    if (pgSchema && pgSchema !== 'public') {
-        return `${quoteId('postgres', pgSchema)}.${quoteId('postgres', typeName)}`;
-    }
-    return quoteId('postgres', typeName);
+    return getPgGrammar(pgSchema).qualifiedType(typeName);
 }
 
 function pgRegclass(name: string, pgSchema?: string): string {
-    // Build a regclass-compatible identifier string with proper quoting for use inside SQL string literals
-    if (pgSchema && pgSchema !== 'public') {
-        return `${quoteId('postgres', pgSchema)}.${quoteId('postgres', name)}`;
-    }
-    return quoteId('postgres', name);
+    // Same form as qualifiedType — used in SQL string literals (quoted identifiers).
+    return getPgGrammar(pgSchema).qualifiedType(name);
 }
 
 function escapeStr(s: string, dialect?: Dialect): string {
-    // MySQL also treats backslashes as escape characters in string literals
-    if (dialect === 'mysql') {
-        s = s.replace(/\\/g, '\\\\');
-    }
+    if (dialect === 'mysql') s = s.replace(/\\/g, '\\\\');
     return s.replace(/'/g, "''");
 }

package/src/database/migration/create/file-generator.ts

@@ -5,6 +5,11 @@ import { getSourceMigrationsDir } from '../helpers';
 import { COMMENT_PREFIX } from './ddl-generator';
 
 export function generateMigrationFile(statements: string[], description: string): string {
+    return writeMigrationFile(buildFileContent(statements), description);
+}
+
+/** Write pre-rendered file content (e.g. builder-based) to a timestamped migration file. */
+export function writeMigrationFile(content: string, description: string): string {
     const migrationsDir = getSourceMigrationsDir();
 
     if (!existsSync(migrationsDir)) {
@@ -16,7 +21,6 @@ export function generateMigrationFile(statements: string[], description: string)
     const filename = `${timestamp}_${slug}.ts`;
     const filePath = path.join(migrationsDir, filename);
 
-    const content = buildFileContent(statements);
     writeFileSync(filePath, content, 'utf8');
 
     return filePath;

package/src/database/migration/create/schema-model.ts

@@ -22,6 +22,8 @@ export interface ColumnSchema {
     isIdentity?: boolean; // PG only: true if GENERATED ... AS IDENTITY (vs sequence-backed serial)
     sequenceName?: string; // PG only: actual sequence name from pg_get_serial_sequence()
     ordinalPosition: number; // 1-based column order
+    /** MySQL only — positioning hint for ALTER TABLE ADD COLUMN. `null` = FIRST, string = AFTER <col>, undefined = no clause. */
+    afterColumn?: string | null;
 }
 
 export interface IndexSchema {

package/src/database/mysql.ts

@@ -1,5 +1,4 @@
 import { ClassType, getClassName } from '@deepkit/core';
-import { Logger } from '@deepkit/logger';
 import { MySQLConnection, MySQLDatabaseAdapter as BaseMySQLDatabaseAdapter } from '@deepkit/mysql';
 import { Database, DatabaseSession } from '@deepkit/orm';
 import { isNonUndefined } from '@deepkit/sql';
@@ -7,7 +6,7 @@ import { databaseAnnotation, ReflectionKind, Type } from '@deepkit/type';
 import { PoolConfig } from 'mariadb';
 
 import { Coordinate } from '.';
-import { getAppConfig, r } from '../app/resolver';
+import { getAppConfig } from '../app/resolver';
 import { globalState } from '../app/state';
 import { BaseDatabase } from './common';
 
@@ -120,21 +119,14 @@ export function createMySQLDatabase(
                 entities.push(...globalState.additionalEntities);
             }
 
-            super(adapter, entities);
-
+            // Mark the adapter so acquireSessionLock can lazy-init the _locks table on first use.
+            // Constructor-time fire-and-forget would race with pool teardown for short-lived CLI
+            // commands like migration:reset that don't issue any DB work.
             if (enableLocksTable) {
-                this.rawExecute(
-                    `CREATE TABLE IF NOT EXISTS \`_locks\` (
-                        \`key\` VARCHAR(255) NOT NULL PRIMARY KEY,
-                        \`createdAt\` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-                        \`lastTouched\` DATETIME
-                    )`
-                )
-                    .then(() => this.rawExecute(`DELETE FROM _locks WHERE lastTouched < NOW() - INTERVAL 1 HOUR`))
-                    .catch(err => {
-                        r(Logger).error(`Could not create _locks table: %s`, err);
-                    });
+                (adapter as unknown as { _enableLocksTable: boolean })._enableLocksTable = true;
             }
+
+            super(adapter, entities);
         }
     };
 }

package/src/database/postgres.ts

@@ -1,12 +1,11 @@
 import { ClassType } from '@deepkit/core';
-import { Logger } from '@deepkit/logger';
 import { Database, DatabaseSession } from '@deepkit/orm';
 import { PostgresConnection, PostgresDatabaseAdapter as BasePostgresDatabaseAdapter } from '@deepkit/postgres';
 import { isNonUndefined } from '@deepkit/sql';
 import { ReflectionKind, Type } from '@deepkit/type';
 import { PoolConfig } from 'pg';
 
-import { getAppConfig, r } from '../app/resolver';
+import { getAppConfig } from '../app/resolver';
 import { globalState } from '../app/state';
 import { BaseDatabase } from './common';
 
@@ -46,6 +45,7 @@ export class PostgresDatabaseAdapter extends BasePostgresDatabaseAdapter {
 }
 
 export interface IPostgresDatabaseAdapterConfig extends PoolConfig {
+    /** Accepted for cross-dialect API parity with createMySQLDatabase. PG uses `pg_advisory_xact_lock` for session locks — no table needed. */
     enableLocksTable?: boolean;
 }
 
@@ -58,7 +58,7 @@ export function createPostgresDatabase(
             const appConfig = getAppConfig();
             const isProduction = appConfig.APP_ENV === 'production';
 
-            const { enableLocksTable, ...otherConfig } = config;
+            const { enableLocksTable: _enableLocksTable, ...otherConfig } = config;
 
             const ssl = appConfig.PG_SSL ? { rejectUnauthorized: appConfig.PG_SSL_REJECT_UNAUTHORIZED ?? true } : undefined;
 
@@ -81,20 +81,6 @@ export function createPostgresDatabase(
             }
 
             super(adapter, entities);
-
-            if (enableLocksTable) {
-                this.rawExecute(
-                    `CREATE TABLE IF NOT EXISTS "_locks" (
-                        "key" VARCHAR(255) NOT NULL PRIMARY KEY,
-                        "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-                        "lastTouched" TIMESTAMP
-                    )`
-                )
-                    .then(() => this.rawExecute(`DELETE FROM "_locks" WHERE "lastTouched" < NOW() - INTERVAL '1 hour'`))
-                    .catch(err => {
-                        r(Logger).error(`Could not create _locks table: %s`, err);
-                    });
-            }
         }
     };
 }

package/src/database/schema/AlterBlueprint.ts

@@ -0,0 +1,85 @@
+import { ColumnSchema, ForeignKeySchema, IndexSchema } from '../migration/create/schema-model';
+import { BlueprintBase } from './BlueprintBase';
+import { ColumnDefinition } from './ColumnDefinition';
+
+/**
+ * Alter-table blueprint. Records discrete operations (add/drop/rename/change column,
+ * add/drop index/FK, set/drop primary key) for an existing table.
+ *
+ * Inherits all column-type methods from BlueprintBase — by default a column added via
+ * `t.string('email')` becomes an ADD COLUMN. Call `.change()` on the returned ColumnDefinition
+ * to mark it as a modification (MODIFY COLUMN / ALTER COLUMN) instead.
+ */
+export class AlterBlueprint extends BlueprintBase {
+    public readonly addedColumns: ColumnSchema[] = [];
+    public readonly modifiedColumns: ColumnSchema[] = [];
+    public readonly droppedColumns: string[] = [];
+    public readonly renamedColumns: { from: string; to: string }[] = [];
+    public readonly addedIndexes: IndexSchema[] = [];
+    public readonly droppedIndexes: string[] = [];
+    public readonly addedForeignKeys: ForeignKeySchema[] = [];
+    public readonly droppedForeignKeys: string[] = [];
+    public newPrimaryKey?: string[];
+    public dropsPrimaryKey = false;
+
+    protected addColumnImpl(col: ColumnSchema): ColumnDefinition {
+        this.addedColumns.push(col);
+        return new ColumnDefinition(this, col);
+    }
+
+    protected addIndexImpl(idx: IndexSchema): void {
+        this.addedIndexes.push(idx);
+    }
+
+    protected addForeignKeyImpl(fk: ForeignKeySchema): void {
+        this.addedForeignKeys.push(fk);
+    }
+
+    dropColumn(name: string): this {
+        this.droppedColumns.push(name);
+        return this;
+    }
+
+    renameColumn(from: string, to: string): this {
+        this.renamedColumns.push({ from, to });
+        return this;
+    }
+
+    /** Drop an index by name. */
+    dropIndex(name: string): this {
+        this.droppedIndexes.push(name);
+        return this;
+    }
+
+    /** Alias of dropIndex — same op at the SQL level, kept for readability. */
+    dropUnique(name: string): this {
+        return this.dropIndex(name);
+    }
+
+    /** Drop a foreign key constraint by name. */
+    dropForeign(name: string): this {
+        this.droppedForeignKeys.push(name);
+        return this;
+    }
+
+    /** Set / replace the table's primary key. */
+    primary(columns: string[]): this {
+        this.newPrimaryKey = columns;
+        return this;
+    }
+
+    /** Drop the existing primary key. Combine with `.primary([...])` to replace. */
+    dropPrimary(): this {
+        this.dropsPrimaryKey = true;
+        return this;
+    }
+
+    /** Called by ColumnDefinition.change() — moves a column from added → modified. */
+    markColumnAsModified(col: ColumnSchema): void {
+        const idx = this.addedColumns.indexOf(col);
+        if (idx >= 0) {
+            this.addedColumns.splice(idx, 1);
+            this.modifiedColumns.push(col);
+        }
+    }
+}

package/src/database/schema/Blueprint.ts

@@ -0,0 +1,43 @@
+import { ColumnSchema, ForeignKeySchema, IndexSchema, TableSchema } from '../migration/create/schema-model';
+import { BlueprintBase } from './BlueprintBase';
+import { ColumnDefinition } from './ColumnDefinition';
+
+/** Create-table blueprint. Records columns + indexes + FKs and renders a TableSchema. */
+export class Blueprint extends BlueprintBase {
+    public readonly columns: ColumnSchema[] = [];
+    public readonly indexes: IndexSchema[] = [];
+    public readonly foreignKeys: ForeignKeySchema[] = [];
+
+    protected addColumnImpl(col: ColumnSchema): ColumnDefinition {
+        this.columns.push(col);
+        return new ColumnDefinition(this, col);
+    }
+
+    protected addIndexImpl(idx: IndexSchema): void {
+        this.indexes.push(idx);
+    }
+
+    protected addForeignKeyImpl(fk: ForeignKeySchema): void {
+        this.foreignKeys.push(fk);
+    }
+
+    /** Composite primary key — replaces single-column .primary() flag with a multi-column PK. */
+    primary(columns: string[]): this {
+        for (const col of this.columns) {
+            col.isPrimaryKey = columns.includes(col.name);
+        }
+        return this;
+    }
+
+    build(): TableSchema {
+        this.columns.forEach((col, i) => {
+            col.ordinalPosition = i + 1;
+        });
+        return {
+            name: this.tableName,
+            columns: this.columns,
+            indexes: this.indexes,
+            foreignKeys: this.foreignKeys
+        };
+    }
+}