@solidxai/core 0.1.11-beta.1 → 0.1.11-beta.12

package/src/services/datasource-introspection.service.ts

@@ -4,12 +4,14 @@ import { getDataSourceToken } from "@nestjs/typeorm";
 import { createHash } from "crypto";
 import * as fs from "fs/promises";
 import * as path from "path";
-import { camelCase, startCase } from "lodash";
+import { camelCase, kebabCase, startCase } from "lodash";
+import { ArrayLiteralExpression, IndentationText, Node, ObjectLiteralExpression, Project, QuoteKind, SyntaxKind, VariableDeclarationKind } from "ts-morph";
 import { DataSource } from "typeorm";
 import { CreateModelMetadataDto } from "src/dtos/create-model-metadata.dto";
 import { DatasourceIntrospectionMappingColumnDto, DatasourceIntrospectionMappingDto } from "src/dtos/datasource-introspection-mapping.dto";
 import { UpdateModelMetaDataDto } from "src/dtos/update-model-metadata.dto";
 import { LegacyTableType } from "src/enums/legacy-table-type.enum";
+import { classify } from "src/helpers/string.helper";
 import type { DatasourceIntrospectionColumn, DatasourceIntrospectionProvider, DatasourceIntrospectionTableRef } from "src/interfaces/datasource-introspection-provider.interface";
 import { ModuleMetadataHelperService } from "src/helpers/module-metadata-helper.service";
 import { ModelMetadataHelperService } from "src/helpers/model-metadata-helper.service";
@@ -17,8 +19,10 @@ import { ModelMetadataRepository } from "src/repository/model-metadata.repositor
 import { ModuleMetadataRepository } from "src/repository/module-metadata.repository";
 import type { ModelMetadata } from "src/entities/model-metadata.entity";
 import { DatasourceManagementService, type DatasourceRecord } from "./datasource-management.service";
+import { CommandService } from "src/helpers/command.service";
 import { FieldMetadataService } from "./field-metadata.service";
 import { ModelMetadataService } from "./model-metadata.service";
+import { ModuleMetadataService } from "./module-metadata.service";
 import { MssqlDatasourceIntrospectionProviderService } from "./datasource-introspection/mssql-datasource-introspection-provider.service";
 import { MysqlDatasourceIntrospectionProviderService } from "./datasource-introspection/mysql-datasource-introspection-provider.service";
 import { PostgresDatasourceIntrospectionProviderService } from "./datasource-introspection/postgres-datasource-introspection-provider.service";
@@ -39,11 +43,16 @@ type TableInventoryRecord = {
     suggestedUserKeyField: string;
     columnCount: number;
     physicalColumnCount: number;
+    hasPrimaryKey: boolean;
+    primaryKeyColumnCount: number;
+    primaryKeyColumnNames: string[];
+    mappingBlockedReason: string | null;
 };
 
 type TableDetailColumnRecord = {
     columnName: string;
     fieldName: string;
+    displayName: string;
     dataType: string;
     solidFieldType: string;
     ormType: string;
@@ -54,6 +63,7 @@ type TableDetailColumnRecord = {
     numericScale: number | null;
     ordinalPosition: number | null;
     isAutoGenerated: boolean;
+    isPrimaryKey: boolean;
     handledBySuperclass: boolean;
     superclassFieldName: string | null;
 };
@@ -81,6 +91,13 @@ type MappingPreviewRecord = {
         note: string;
         missingSystemColumns: string[];
     };
+    datasourceFile: {
+        filePath: string;
+        created: boolean;
+        updated: boolean;
+        entityRegistered: boolean;
+        migrationGlobRegistered: boolean;
+    };
     summary: {
         includedColumnNames: string[];
         removedColumnNames: string[];
@@ -119,6 +136,105 @@ type SystemColumnDefinition = {
     isUnique?: boolean;
 };
 
+type DatasourceTypeFamily =
+    | "boolean"
+    | "bigint"
+    | "int"
+    | "numeric"
+    | "decimal"
+    | "float"
+    | "date"
+    | "time"
+    | "datetime"
+    | "datetimeWithTimezone"
+    | "json"
+    | "jsonb"
+    | "uuid"
+    | "longText"
+    | "mediumText"
+    | "shortText"
+    | "unicodeShortText";
+
+const DATASOURCE_TYPE_FAMILY_ALIASES: Record<DatasourceTypeFamily, string[]> = {
+    boolean: ["bit", "bool", "boolean"],
+    bigint: ["bigint"],
+    int: ["int", "integer", "smallint", "tinyint"],
+    numeric: ["numeric"],
+    decimal: ["decimal", "money", "smallmoney"],
+    float: ["float", "double", "double precision", "real", "float4", "float8"],
+    date: ["date"],
+    time: ["time", "time without time zone", "time with time zone"],
+    datetime: ["datetime", "datetime2", "smalldatetime", "timestamp", "timestamp without time zone"],
+    datetimeWithTimezone: ["timestamptz", "timestamp with time zone"],
+    json: ["json", "simple-json", "simplejson"],
+    jsonb: ["jsonb"],
+    uuid: ["uniqueidentifier", "uuid"],
+    longText: ["text", "ntext", "longtext", "clob"],
+    mediumText: ["mediumtext"],
+    shortText: ["varchar", "char", "citext"],
+    unicodeShortText: ["nvarchar", "nchar"],
+};
+
+const ORM_TYPE_BY_DATASOURCE_FAMILY: Record<string, Partial<Record<DatasourceTypeFamily, string>>> = {
+    mssql: {
+        boolean: "bit",
+        bigint: "bigint",
+        int: "int",
+        numeric: "numeric",
+        decimal: "decimal",
+        float: "decimal",
+        date: "date",
+        time: "time",
+        datetime: "datetime",
+        datetimeWithTimezone: "datetime",
+        json: "simple-json",
+        jsonb: "simple-json",
+        uuid: "uniqueidentifier",
+        longText: "text",
+        mediumText: "text",
+        shortText: "varchar",
+        unicodeShortText: "nvarchar",
+    },
+    mysql: {
+        boolean: "boolean",
+        bigint: "int",
+        int: "int",
+        numeric: "decimal",
+        decimal: "decimal",
+        float: "double",
+        date: "date",
+        time: "time",
+        datetime: "datetime",
+        datetimeWithTimezone: "datetime",
+        json: "json",
+        jsonb: "json",
+        uuid: "varchar",
+        longText: "longtext",
+        mediumText: "mediumtext",
+        shortText: "varchar",
+        unicodeShortText: "varchar",
+    },
+    postgres: {
+        boolean: "boolean",
+        bigint: "bigint",
+        int: "integer",
+        numeric: "decimal",
+        decimal: "decimal",
+        float: "decimal",
+        date: "date",
+        time: "time",
+        datetime: "timestamp",
+        datetimeWithTimezone: "timestamptz",
+        json: "json",
+        jsonb: "jsonb",
+        uuid: "uuid",
+        longText: "text",
+        mediumText: "text",
+        shortText: "varchar",
+        unicodeShortText: "varchar",
+    },
+};
+
 @Injectable()
 export class DatasourceIntrospectionService {
     private readonly supportedDatasourceTypes = new Set(["mssql", "mysql", "postgres"]);
@@ -132,6 +248,8 @@ export class DatasourceIntrospectionService {
         private readonly modelMetadataHelperService: ModelMetadataHelperService,
         private readonly fieldMetadataService: FieldMetadataService,
         private readonly modelMetadataService: ModelMetadataService,
+        private readonly moduleMetadataService: ModuleMetadataService,
+        private readonly commandService: CommandService,
         private readonly mssqlProvider: MssqlDatasourceIntrospectionProviderService,
         private readonly mysqlProvider: MysqlDatasourceIntrospectionProviderService,
         private readonly postgresProvider: PostgresDatasourceIntrospectionProviderService,
@@ -266,11 +384,6 @@ export class DatasourceIntrospectionService {
             ? await this.modelMetadataService.update(mappingDto.modelId, plan.modelPayload as UpdateModelMetaDataDto)
             : await this.modelMetadataService.create(plan.modelPayload as CreateModelMetadataDto);
 
-        if (plan.migration.willGenerate && plan.migration.content && plan.migration.filePath) {
-            await fs.mkdir(path.dirname(plan.migration.filePath), { recursive: true });
-            await fs.writeFile(plan.migration.filePath, plan.migration.content, "utf8");
-        }
-
         const persistedModelId = mappingDto.modelId ?? (persistedModel as ModelMetadata | undefined)?.id ?? null;
 
         return {
@@ -278,15 +391,106 @@ export class DatasourceIntrospectionService {
                 modelId: persistedModelId,
                 operation: plan.operation,
                 metadataJson: plan.metadataJson,
+                summary: plan.summary,
+            },
+        };
+    }
+
+    async createMigrationArtifacts(moduleId: number, mappingDto: DatasourceIntrospectionMappingDto) {
+        const plan = await this.buildMappingPreview(moduleId, mappingDto);
+        const module = await this.loadModule(moduleId);
+        const datasource = this.requireDatasource(mappingDto.dataSource);
+
+        if (!mappingDto.modelId) {
+            throw new BadRequestException("Persist the model mapping first so the generated entity can be registered before creating migration artifacts.");
+        }
+
+        const migrationWritten = await this.writeMigrationFile(plan.migration);
+
+        const datasourceFile = await this.syncTypeormDatasourceFile(
+            module.name,
+            datasource,
+            plan.modelPayload.singularName,
+        );
+
+        return {
+            data: {
+                modelId: mappingDto.modelId,
+                operation: plan.operation,
                 migration: {
                     ...plan.migration,
-                    written: Boolean(plan.migration.willGenerate && plan.migration.filePath),
+                    written: migrationWritten,
                 },
+                datasourceFile,
                 summary: plan.summary,
             },
         };
     }
 
+    async generateCode(moduleId: number) {
+        await this.loadModule(moduleId);
+        const output = await this.moduleMetadataService.generateCodeViaCtl(moduleId);
+
+        return {
+            data: {
+                moduleId,
+                output,
+                message: "Module code generation completed.",
+            },
+        };
+    }
+
+    async runMigration(moduleId: number, datasourceName: string) {
+        const module = await this.loadModule(moduleId);
+        const datasource = this.requireDatasource(datasourceName);
+        const cwd = path.join(process.cwd(), "..");
+        const outputs: string[] = [];
+
+        const migrationOutput = await this.commandService.executeCommandWithArgs({
+            command: "npx",
+            args: ["-y", "@solidxai/solidctl@latest", "migration", "-d", datasource.name, "run"],
+            cwd,
+        });
+        outputs.push([
+            `npx @solidxai/solidctl@latest migration -d ${datasource.name} run`,
+            migrationOutput,
+        ].filter(Boolean).join("\n"));
+
+        const buildOutput = await this.commandService.executeCommandWithArgs({
+            command: "npx",
+            args: ["-y", "@solidxai/solidctl@latest", "build"],
+            cwd,
+        });
+        outputs.push([
+            "npx @solidxai/solidctl@latest build",
+            buildOutput,
+        ].filter(Boolean).join("\n"));
+
+        const seedOutput = await this.commandService.executeCommandWithArgs({
+            command: "npx",
+            args: ["-y", "@solidxai/solidctl@latest", "seed", "--modules-to-seed", module.name],
+            cwd,
+        });
+        outputs.push([
+            `npx @solidxai/solidctl@latest seed --modules-to-seed ${module.name}`,
+            seedOutput,
+        ].filter(Boolean).join("\n"));
+
+        return {
+            data: {
+                moduleId,
+                datasource: datasource.name,
+                output: outputs.join("\n\n"),
+                command: [
+                    `npx @solidxai/solidctl@latest migration -d ${datasource.name} run`,
+                    "npx @solidxai/solidctl@latest build",
+                    `npx @solidxai/solidctl@latest seed --modules-to-seed ${module.name}`,
+                ].join("\n"),
+                message: `Migration, build, and seed completed successfully for datasource "${datasource.name}".`,
+            },
+        };
+    }
+
     private async buildMappingPreview(moduleId: number, mappingDto: DatasourceIntrospectionMappingDto): Promise<MappingPreviewRecord> {
         const module = await this.loadModule(moduleId);
         const datasource = this.requireDatasource(mappingDto.dataSource);
@@ -301,6 +505,8 @@ export class DatasourceIntrospectionService {
         if (!tableRecord) {
             throw new NotFoundException(`Table "${mappingDto.tableName}" was not found on datasource "${datasource.name}".`);
         }
+        const tableColumns = inventory.columnsByKey.get(tableKey) ?? [];
+        this.validateTablePrimaryKeyForMapping(tableRecord, tableColumns, mappingDto);
 
         const existingModel = mappingDto.mapped && mappingDto.modelId
             ? await this.modelMetadataRepository.findOne({
@@ -318,14 +524,14 @@ export class DatasourceIntrospectionService {
             throw new NotFoundException(`Mapped model "${mappingDto.modelId}" was not found.`);
         }
 
-        const reviewedModel = this.normalizeReviewedMetadataModel(mappingDto.reviewedModel, mappingDto);
+        const reviewedModel = this.normalizeReviewedMetadataModel(mappingDto.reviewedModel, mappingDto, tableColumns);
         const modelPayload = reviewedModel
             ? this.buildModelPayloadFromReviewedModel(moduleId, mappingDto, existingModel, reviewedModel)
             : this.buildModelPayload(moduleId, mappingDto, existingModel);
         const metadataJson = reviewedModel
             ? await this.buildMetadataJsonPreviewFromReviewedModel(module.name, reviewedModel)
             : await this.buildMetadataJsonPreview(module.name, mappingDto, existingModel);
-        const migration = await this.buildMigrationPreview(module.name, datasource, mappingDto, inventory.columnsByKey.get(tableKey) ?? []);
+        const migration = await this.buildMigrationPreview(module.name, datasource, mappingDto, tableColumns);
         const includedColumnNames = mappingDto.columns
             .filter((column) => !column.handledBySuperclass && column.include)
             .map((column) => column.columnName);
@@ -338,6 +544,13 @@ export class DatasourceIntrospectionService {
             mappedModelId: mappingDto.modelId ?? null,
             metadataJson,
             migration,
+            datasourceFile: {
+                filePath: path.resolve(process.cwd(), "src", `typeorm-${datasource.name}-datasource.ts`),
+                created: false,
+                updated: false,
+                entityRegistered: false,
+                migrationGlobRegistered: false,
+            },
             summary: {
                 includedColumnNames,
                 removedColumnNames,
@@ -399,6 +612,11 @@ export class DatasourceIntrospectionService {
         existingModel: ModelMetadata | null,
         reviewedModel: ReviewedMetadataModel,
     ): CreateModelMetadataDto | UpdateModelMetaDataDto {
+        const resolvedUserKeyFieldName = this.resolveReviewedUserKeyFieldName(
+            reviewedModel.fields,
+            reviewedModel.userKeyFieldUserKey,
+            mappingDto.userKeyField,
+        );
         const systemFieldPayloads = existingModel
             ? existingModel.fields
                 .filter((field) => field.isSystem)
@@ -410,7 +628,7 @@ export class DatasourceIntrospectionService {
             return {
                 ...field,
                 ...(matchedExistingField?.id ? { id: matchedExistingField.id } : {}),
-                isUserKey: field.name === reviewedModel.userKeyFieldUserKey,
+                isUserKey: field.name === resolvedUserKeyFieldName,
                 isSystem: field.isSystem ?? false,
             };
         });
@@ -444,6 +662,11 @@ export class DatasourceIntrospectionService {
     ) {
         const filePath = await this.moduleMetadataHelperService.getModuleMetadataFilePath(moduleName);
         const previewFields = await this.buildMetadataPreviewFields(mappingDto, existingModel);
+        const resolvedUserKeyFieldName = this.resolveReviewedUserKeyFieldName(
+            previewFields,
+            mappingDto.userKeyField,
+            mappingDto.userKeyField,
+        ) ?? mappingDto.userKeyField;
 
         return {
             filePath,
@@ -455,7 +678,7 @@ export class DatasourceIntrospectionService {
                 dataSource: mappingDto.dataSource,
                 dataSourceType: mappingDto.dataSourceType,
                 tableName: mappingDto.tableName,
-                userKeyFieldUserKey: mappingDto.userKeyField,
+                userKeyFieldUserKey: resolvedUserKeyFieldName,
                 isChild: false,
                 legacyTableType: mappingDto.legacyTableType,
                 parentModelUserKey: "",
@@ -523,10 +746,6 @@ export class DatasourceIntrospectionService {
 
         const serialized = Array.from(finalFields.values())
             .filter((field) => !field.isSystem)
-            .map((field) => ({
-                ...field,
-                isUserKey: field.name === mappingDto.userKeyField,
-            }))
             .sort((left, right) => {
                 const leftOrder = typeof left.id === "number" ? left.id : Number.MAX_SAFE_INTEGER;
                 const rightOrder = typeof right.id === "number" ? right.id : Number.MAX_SAFE_INTEGER;
@@ -542,6 +761,16 @@ export class DatasourceIntrospectionService {
             previewFields.push(await this.fieldMetadataService.createFieldConfig(field as any));
         }
 
+        const resolvedUserKeyFieldName = this.resolveReviewedUserKeyFieldName(
+            previewFields,
+            mappingDto.userKeyField,
+            mappingDto.userKeyField,
+        );
+
+        for (const field of previewFields) {
+            field.isUserKey = field.name === resolvedUserKeyFieldName;
+        }
+
         return previewFields;
     }
 
@@ -608,9 +837,18 @@ export class DatasourceIntrospectionService {
         return rest;
     }
 
+    private sanitizeConfiguredFieldPayload(fieldConfig: Record<string, any> | undefined) {
+        if (!fieldConfig || typeof fieldConfig !== "object" || Array.isArray(fieldConfig)) {
+            return {};
+        }
+
+        return this.sanitizeExistingFieldPayload(fieldConfig);
+    }
+
     private normalizeReviewedMetadataModel(
         reviewedModel: Record<string, any> | undefined,
         mappingDto: DatasourceIntrospectionMappingDto,
+        tableColumns: DatasourceIntrospectionColumn[],
     ): ReviewedMetadataModel | null {
         if (!reviewedModel) {
             return null;
@@ -670,11 +908,24 @@ export class DatasourceIntrospectionService {
             fieldNames.add(loweredName);
         }
 
-        const userKeyFieldUserKey = readString("userKeyFieldUserKey");
-        if (!normalizedFields.some((field) => field.name === userKeyFieldUserKey && !field.isMarkedForRemoval)) {
+        const requestedUserKeyFieldUserKey = readString("userKeyFieldUserKey");
+        const resolvedUserKeyFieldName = this.resolveReviewedUserKeyFieldName(
+            normalizedFields,
+            requestedUserKeyFieldUserKey,
+            mappingDto.userKeyField,
+        );
+        const inheritedGeneratedIdUserKey = this.isGeneratedIdInheritedUserKey(
+            mappingDto.legacyTableType,
+            requestedUserKeyFieldUserKey,
+        );
+        if (!resolvedUserKeyFieldName && !inheritedGeneratedIdUserKey) {
             throw new BadRequestException("Reviewed metadata JSON must keep the selected userKeyFieldUserKey in the fields array.");
         }
 
+        this.validateReviewedPrimaryKeyFields(normalizedFields, tableColumns);
+
+        const userKeyFieldUserKey = resolvedUserKeyFieldName ?? requestedUserKeyFieldUserKey;
+
         return {
             singularName: readString("singularName"),
             pluralName: readString("pluralName"),
@@ -693,11 +944,54 @@ export class DatasourceIntrospectionService {
             internationalisation: readBoolean("internationalisation"),
             fields: normalizedFields.map((field) => ({
                 ...field,
-                isUserKey: field.name === userKeyFieldUserKey,
+                isUserKey: field.name === resolvedUserKeyFieldName,
             })),
         };
     }
 
+    private resolveReviewedUserKeyFieldName(
+        reviewedFields: Array<Record<string, any>>,
+        requestedUserKeyFieldName: string,
+        fallbackUserKeyFieldName?: string,
+    ) {
+        const activeFields = reviewedFields.filter((field) => !field.isMarkedForRemoval);
+        const normalizedRequested = `${requestedUserKeyFieldName ?? ""}`.trim().toLowerCase();
+        const normalizedFallback = `${fallbackUserKeyFieldName ?? ""}`.trim().toLowerCase();
+
+        const byExactRequested = activeFields.find((field) => field.name?.toLowerCase?.() === normalizedRequested);
+        if (byExactRequested) {
+            return byExactRequested.name;
+        }
+
+        const byExistingUserKeyFlag = activeFields.find((field) => field.isUserKey);
+        if (byExistingUserKeyFlag) {
+            return byExistingUserKeyFlag.name;
+        }
+
+        const byPrimaryKeyFallback = activeFields.find((field) => {
+            if (!field.isPrimaryKey) {
+                return false;
+            }
+
+            const normalizedName = `${field.name ?? ""}`.trim().toLowerCase();
+            return normalizedName === normalizedFallback || normalizedName === "id" || normalizedName === "legacyid";
+        });
+        if (byPrimaryKeyFallback) {
+            return byPrimaryKeyFallback.name;
+        }
+
+        const byFallbackFieldName = activeFields.find((field) => field.name?.toLowerCase?.() === normalizedFallback);
+        return byFallbackFieldName?.name ?? null;
+    }
+
+    private isGeneratedIdInheritedUserKey(
+        legacyTableType: LegacyTableType,
+        requestedUserKeyFieldName: string | null | undefined,
+    ) {
+        return legacyTableType === LegacyTableType.GENERATED_ID
+            && `${requestedUserKeyFieldName ?? ""}`.trim().toLowerCase() === "id";
+    }
+
     private normalizeReviewedField(field: any, index: number) {
         if (!field || typeof field !== "object" || Array.isArray(field)) {
             throw new BadRequestException(`Reviewed metadata JSON field at index ${index} is not a valid object.`);
@@ -762,34 +1056,39 @@ export class DatasourceIntrospectionService {
         existingField?: any,
     ) {
         const preserved = existingField ? this.sanitizeExistingFieldPayload(existingField) : {};
+        const configured = this.sanitizeConfiguredFieldPayload(column.fieldConfig);
+        const merged = {
+            ...preserved,
+            ...configured,
+        };
         const maxLength =
             column.characterMaximumLength && ["shortText", "longText"].includes(column.solidFieldType)
                 ? column.characterMaximumLength
-                : preserved.max;
+                : merged.max;
 
         return {
-            ...preserved,
+            ...merged,
             ...(column.fieldId ? { id: column.fieldId } : {}),
             name: column.fieldName,
-            displayName: preserved.displayName ?? startCase(column.fieldName),
-            description: preserved.description ?? "",
+            displayName: column.displayName?.trim() || merged.displayName || startCase(column.fieldName),
+            description: merged.description ?? "",
             type: column.solidFieldType,
             ormType: column.ormType,
-            length: preserved.length ?? column.characterMaximumLength ?? undefined,
-            defaultValue: preserved.defaultValue ?? column.defaultValue ?? undefined,
-            required: preserved.required ?? (!column.nullable || column.isPrimaryKey),
-            unique: preserved.unique ?? false,
-            encrypt: preserved.encrypt ?? false,
-            index: preserved.index ?? false,
+            length: merged.length ?? column.characterMaximumLength ?? undefined,
+            defaultValue: merged.defaultValue ?? column.defaultValue ?? undefined,
+            required: merged.required ?? (!column.nullable || column.isPrimaryKey),
+            unique: merged.unique ?? false,
+            encrypt: merged.encrypt ?? false,
+            index: merged.index ?? false,
             max: maxLength ?? undefined,
-            min: preserved.min ?? undefined,
-            private: preserved.private ?? false,
-            isSystem: preserved.isSystem ?? false,
+            min: merged.min ?? undefined,
+            private: merged.private ?? false,
+            isSystem: merged.isSystem ?? false,
             isMarkedForRemoval: false,
             columnName: column.columnName,
             isUserKey: mappingDto.userKeyField === column.fieldName,
-            enableAuditTracking: preserved.enableAuditTracking ?? mappingDto.enableAuditTracking,
-            isMultiSelect: preserved.isMultiSelect ?? false,
+            enableAuditTracking: merged.enableAuditTracking ?? mappingDto.enableAuditTracking,
+            isMultiSelect: merged.isMultiSelect ?? false,
             isPrimaryKey: column.isPrimaryKey,
         };
     }
@@ -891,11 +1190,8 @@ export class DatasourceIntrospectionService {
 
         const upColumnStatements = missingSystemColumns.map((definition) => {
             const columnLiteral = this.renderTableColumnLiteral(definition);
-            return [
-                `        if (!(await queryRunner.hasColumn(tableName, ${JSON.stringify(definition.columnName)}))) {`,
-                `            await queryRunner.addColumn(tableName, new TableColumn(${columnLiteral}));`,
-                "        }",
-            ].join("\n");
+            return `        if (!(await queryRunner.hasColumn(tableName, ${JSON.stringify(definition.columnName)})))\n`
+                + `            await queryRunner.addColumn(tableName, new TableColumn(${columnLiteral}));`;
         }).join("\n\n");
 
         const postUpStatements: string[] = [];
@@ -904,12 +1200,11 @@ export class DatasourceIntrospectionService {
                 [
                     "        {",
                     "            const table = await queryRunner.getTable(tableName);",
-                    `            if (table && !table.indices.some((index) => index.name === ${JSON.stringify(deletedAtIndexName)})) {`,
-                    "                await queryRunner.createIndex(tableName, new TableIndex({",
-                    `                    name: ${JSON.stringify(deletedAtIndexName)},`,
-                    "                    columnNames: [\"ss_deleted_at\"],",
-                    "                }));",
-                    "            }",
+                    `            if (table && !table.indices.some((index) => index.name === ${JSON.stringify(deletedAtIndexName)}))`,
+                    `                await queryRunner.createIndex(tableName, new TableIndex(${this.renderTableIndexLiteral({
+                        name: deletedAtIndexName,
+                        columnNames: ["ss_deleted_at"],
+                    })}));`,
                     "        }",
                 ].join("\n"),
             );
@@ -919,13 +1214,12 @@ export class DatasourceIntrospectionService {
                 [
                     "        {",
                     "            const table = await queryRunner.getTable(tableName);",
-                    `            if (table && !table.indices.some((index) => index.name === ${JSON.stringify(generatedIdUniqueName)})) {`,
-                    "                await queryRunner.createIndex(tableName, new TableIndex({",
-                    `                    name: ${JSON.stringify(generatedIdUniqueName)},`,
-                    "                    columnNames: [\"ss_id\"],",
-                    "                    isUnique: true,",
-                    "                }));",
-                    "            }",
+                    `            if (table && !table.indices.some((index) => index.name === ${JSON.stringify(generatedIdUniqueName)}))`,
+                    `                await queryRunner.createIndex(tableName, new TableIndex(${this.renderTableIndexLiteral({
+                        name: generatedIdUniqueName,
+                        columnNames: ["ss_id"],
+                        isUnique: true,
+                    })}));`,
                     "        }",
                 ].join("\n"),
             );
@@ -938,9 +1232,8 @@ export class DatasourceIntrospectionService {
                     "        {",
                     "            const table = await queryRunner.getTable(tableName);",
                     `            const index = table?.indices.find((entry) => entry.name === ${JSON.stringify(generatedIdUniqueName)});`,
-                    "            if (index) {",
+                    "            if (index)",
                     "                await queryRunner.dropIndex(tableName, index);",
-                    "            }",
                     "        }",
                 ].join("\n"),
             );
@@ -951,9 +1244,8 @@ export class DatasourceIntrospectionService {
                     "        {",
                     "            const table = await queryRunner.getTable(tableName);",
                     `            const index = table?.indices.find((entry) => entry.name === ${JSON.stringify(deletedAtIndexName)});`,
-                    "            if (index) {",
+                    "            if (index)",
                     "                await queryRunner.dropIndex(tableName, index);",
-                    "            }",
                     "        }",
                 ].join("\n"),
             );
@@ -962,11 +1254,8 @@ export class DatasourceIntrospectionService {
             ...missingSystemColumns
                 .slice()
                 .reverse()
-                .map((definition) => [
-                    `        if (await queryRunner.hasColumn(tableName, ${JSON.stringify(definition.columnName)})) {`,
-                    `            await queryRunner.dropColumn(tableName, ${JSON.stringify(definition.columnName)});`,
-                    "        }",
-                ].join("\n")),
+                .map((definition) => `        if (await queryRunner.hasColumn(tableName, ${JSON.stringify(definition.columnName)}))\n`
+                    + `            await queryRunner.dropColumn(tableName, ${JSON.stringify(definition.columnName)});`),
         );
 
         return [
@@ -992,29 +1281,41 @@ export class DatasourceIntrospectionService {
 
     private renderTableColumnLiteral(definition: SystemColumnDefinition) {
         const properties: string[] = [
-            `{\n                name: ${JSON.stringify(definition.columnName)},`,
-            `                type: ${JSON.stringify(definition.type)},`,
+            `name: ${JSON.stringify(definition.columnName)}`,
+            `type: ${JSON.stringify(definition.type)}`,
         ];
 
         if (definition.length) {
-            properties.push(`                length: ${JSON.stringify(definition.length)},`);
+            properties.push(`length: ${JSON.stringify(definition.length)}`);
         }
         if (typeof definition.isNullable === "boolean") {
-            properties.push(`                isNullable: ${definition.isNullable},`);
+            properties.push(`isNullable: ${definition.isNullable}`);
         }
         if (definition.defaultExpression) {
-            properties.push(`                default: ${JSON.stringify(definition.defaultExpression)},`);
+            properties.push(`default: ${JSON.stringify(definition.defaultExpression)}`);
         }
         if (definition.isGenerated) {
-            properties.push("                isGenerated: true,");
-            properties.push("                generationStrategy: \"increment\",");
+            properties.push("isGenerated: true");
+            properties.push("generationStrategy: \"increment\"");
         }
         if (definition.isUnique) {
-            properties.push("                isUnique: true,");
+            properties.push("isUnique: true");
+        }
+
+        return `{ ${properties.join(", ")}, }`;
+    }
+
+    private renderTableIndexLiteral(definition: { name: string; columnNames: string[]; isUnique?: boolean }) {
+        const properties: string[] = [
+            `name: ${JSON.stringify(definition.name)}`,
+            `columnNames: ${JSON.stringify(definition.columnNames)}`,
+        ];
+
+        if (definition.isUnique) {
+            properties.push("isUnique: true");
         }
 
-        properties.push("            }");
-        return properties.join("\n");
+        return `{ ${properties.join(", ")}, }`;
     }
 
     private buildMigrationObjectName(prefix: string, tableName: string, columnName: string) {
@@ -1050,13 +1351,15 @@ export class DatasourceIntrospectionService {
     private async buildTableInventory(datasource: DatasourceRecord) {
         const provider = this.getProvider(datasource.type);
         const runtimeDataSource = this.resolveDataSourceByName(datasource.name);
-        const [tables, columns, models] = await Promise.all([
+        const [rawTables, rawColumns, models] = await Promise.all([
             provider.listTables(runtimeDataSource),
             provider.listColumns(runtimeDataSource),
             this.modelMetadataRepository.find({ relations: { module: true } as any }),
         ]);
+        const tables = rawTables.filter((table) => !this.isSolidxInternalTableName(table.tableName));
+        const columns = rawColumns.filter((column) => !this.isSolidxInternalTableName(column.tableName));
 
-        const modelMap = this.buildModelMap(models);
+        const modelLookup = this.buildModelLookup(models);
         const columnsByKey = this.groupColumnsByTable(columns);
         const tableKeys = new Set<string>();
 
@@ -1080,8 +1383,10 @@ export class DatasourceIntrospectionService {
 
                 const suggestedLegacyTableType = this.detectLegacyTableType(datasource.type, tableColumns);
                 const suggestedIdColumn = this.getSuggestedIdColumn(datasource.type, tableColumns, suggestedLegacyTableType);
-                const mappedModel = modelMap.get(this.toModelMapKey(datasource.name, tableName)) ?? null;
+                const mappedModel = this.resolveMappedModel(modelLookup, datasource.name, tableName);
                 const physicalColumns = tableColumns.filter((column) => !this.isHandledBySuperclass(column.columnName, suggestedLegacyTableType));
+                const primaryKeyColumns = tableColumns.filter((column) => column.isPrimaryKey);
+                const hasPrimaryKey = primaryKeyColumns.length > 0;
 
                 return {
                     schema,
@@ -1099,6 +1404,12 @@ export class DatasourceIntrospectionService {
                     suggestedUserKeyField: this.buildUserKeyCandidates(tableColumns)[0]?.name ?? "id",
                     columnCount: tableColumns.length,
                     physicalColumnCount: physicalColumns.length,
+                    hasPrimaryKey,
+                    primaryKeyColumnCount: primaryKeyColumns.length,
+                    primaryKeyColumnNames: primaryKeyColumns.map((column) => column.columnName),
+                    mappingBlockedReason: hasPrimaryKey
+                        ? null
+                        : this.buildMissingPrimaryKeyMessage(tableName),
                 } satisfies TableInventoryRecord;
             })
             .filter((record): record is TableInventoryRecord => Boolean(record))
@@ -1119,19 +1430,52 @@ export class DatasourceIntrospectionService {
         };
     }
 
-    private buildModelMap(models: ModelMetadata[]) {
-        const map = new Map<string, ModelMetadata>();
+    private buildModelLookup(models: ModelMetadata[]) {
+        const byDatasourceAndTable = new Map<string, ModelMetadata>();
+        const byTableName = new Map<string, ModelMetadata[]>();
 
         for (const model of models) {
             if (!model.tableName) {
                 continue;
             }
 
-            map.set(this.toModelMapKey(model.dataSource, model.tableName), model);
-            map.set(this.toModelMapKey("*", model.tableName), model);
+            byDatasourceAndTable.set(this.toModelMapKey(model.dataSource, model.tableName), model);
+
+            const normalizedTableName = model.tableName.trim().toLowerCase();
+            const bucket = byTableName.get(normalizedTableName);
+            if (bucket) {
+                bucket.push(model);
+                continue;
+            }
+
+            byTableName.set(normalizedTableName, [model]);
         }
 
-        return map;
+        return {
+            byDatasourceAndTable,
+            byTableName,
+        };
+    }
+
+    private resolveMappedModel(
+        lookup: {
+            byDatasourceAndTable: Map<string, ModelMetadata>;
+            byTableName: Map<string, ModelMetadata[]>;
+        },
+        datasourceName: string,
+        tableName: string,
+    ) {
+        const exactMatch = lookup.byDatasourceAndTable.get(this.toModelMapKey(datasourceName, tableName));
+        if (exactMatch) {
+            return exactMatch;
+        }
+
+        const fallbackMatches = lookup.byTableName.get(tableName.trim().toLowerCase()) ?? [];
+        if (fallbackMatches.length === 1) {
+            return fallbackMatches[0];
+        }
+
+        return fallbackMatches[0] ?? null;
     }
 
     private groupColumnsByTable(columns: DatasourceIntrospectionColumn[]) {
@@ -1151,6 +1495,10 @@ export class DatasourceIntrospectionService {
         return grouped;
     }
 
+    private isSolidxInternalTableName(tableName: string | null | undefined) {
+        return typeof tableName === "string" && tableName.toLowerCase().startsWith("ss_");
+    }
+
     private detectLegacyTableType(datasourceType: string, columns: DatasourceIntrospectionColumn[]): LegacyTableType {
         const normalizedDatasourceType = datasourceType.toLowerCase();
         const hasExistingGeneratedId = columns.some((column) => column.isAutoGenerated);
@@ -1239,13 +1587,17 @@ export class DatasourceIntrospectionService {
         datasourceType: string,
     ): TableDetailColumnRecord {
         const superclassFieldName = this.getSuperclassFieldName(column.columnName, legacyTableType);
+        const normalizedColumnName = column.columnName.toLowerCase();
         const fieldName = legacyTableType === LegacyTableType.EXISTING_ID && column.isAutoGenerated
             ? "id"
-            : this.toFieldName(column.columnName);
+            : legacyTableType === LegacyTableType.GENERATED_ID && normalizedColumnName === "id"
+                ? "legacyId"
+                : this.toFieldName(column.columnName);
 
         return {
             columnName: column.columnName,
             fieldName,
+            displayName: startCase(fieldName),
             dataType: column.dataType,
             solidFieldType: this.toSolidFieldType(column),
             ormType: this.toOrmFieldType(column, datasourceType),
@@ -1256,11 +1608,72 @@ export class DatasourceIntrospectionService {
             numericScale: column.numericScale,
             ordinalPosition: column.ordinalPosition,
             isAutoGenerated: column.isAutoGenerated,
+            isPrimaryKey: column.isPrimaryKey,
             handledBySuperclass: Boolean(superclassFieldName),
             superclassFieldName,
         };
     }
 
+    private validateTablePrimaryKeyForMapping(
+        tableRecord: TableInventoryRecord,
+        tableColumns: DatasourceIntrospectionColumn[],
+        mappingDto: DatasourceIntrospectionMappingDto,
+    ) {
+        const detectedPrimaryKeyColumns = tableColumns.filter((column) => column.isPrimaryKey);
+        if (!detectedPrimaryKeyColumns.length) {
+            throw new BadRequestException(tableRecord.mappingBlockedReason ?? this.buildMissingPrimaryKeyMessage(tableRecord.tableName));
+        }
+
+        const requestColumnsByName = new Map(
+            mappingDto.columns.map((column) => [column.columnName.trim().toLowerCase(), column]),
+        );
+
+        for (const primaryKeyColumn of detectedPrimaryKeyColumns) {
+            const matchingRequestColumn = requestColumnsByName.get(primaryKeyColumn.columnName.trim().toLowerCase());
+            if (!matchingRequestColumn) {
+                throw new BadRequestException(`Primary key column "${primaryKeyColumn.columnName}" must remain present in the mapping request for table "${tableRecord.tableName}".`);
+            }
+
+            if (!matchingRequestColumn.include) {
+                throw new BadRequestException(`Primary key column "${primaryKeyColumn.columnName}" cannot be excluded from the mapping for table "${tableRecord.tableName}".`);
+            }
+
+            if (!matchingRequestColumn.isPrimaryKey) {
+                throw new BadRequestException(`Primary key column "${primaryKeyColumn.columnName}" must stay marked as isPrimaryKey for table "${tableRecord.tableName}".`);
+            }
+        }
+    }
+
+    private validateReviewedPrimaryKeyFields(
+        reviewedFields: Array<Record<string, any>>,
+        tableColumns: DatasourceIntrospectionColumn[],
+    ) {
+        const detectedPrimaryKeyColumns = tableColumns.filter((column) => column.isPrimaryKey);
+        if (!detectedPrimaryKeyColumns.length) {
+            return;
+        }
+
+        const activeReviewedFields = reviewedFields.filter((field) => !field.isMarkedForRemoval);
+
+        for (const primaryKeyColumn of detectedPrimaryKeyColumns) {
+            const matchingReviewedField = activeReviewedFields.find((field) =>
+                `${field.columnName ?? ""}`.trim().toLowerCase() === primaryKeyColumn.columnName.trim().toLowerCase(),
+            );
+
+            if (!matchingReviewedField) {
+                throw new BadRequestException(`Reviewed metadata JSON must keep datasource primary key column "${primaryKeyColumn.columnName}" in the fields array.`);
+            }
+
+            if (!matchingReviewedField.isPrimaryKey) {
+                throw new BadRequestException(`Reviewed metadata JSON must keep datasource primary key column "${primaryKeyColumn.columnName}" marked with isPrimaryKey: true.`);
+            }
+        }
+    }
+
+    private buildMissingPrimaryKeyMessage(tableName: string) {
+        return `Table "${tableName}" cannot be mapped because the datasource table does not define any primary key. Add a real primary key to the table before continuing with SolidX mapping.`;
+    }
+
     private getSuperclassFieldName(columnName: string, legacyTableType: LegacyTableType) {
         return this.getLegacySuperclassFieldName(columnName, legacyTableType);
     }
@@ -1298,109 +1711,80 @@ export class DatasourceIntrospectionService {
         return "LegacyCommonEntityWithExistingId";
     }
 
-    private toSolidFieldType(column: DatasourceIntrospectionColumn) {
-        const normalized = column.dataType.toLowerCase();
-        const charLength = column.characterMaximumLength ?? null;
-
-        if (["bit", "bool", "boolean"].includes(normalized)) {
-            return "boolean";
-        }
-
-        if (["bigint"].includes(normalized)) {
-            return "bigint";
-        }
+    private getDatasourceTypeFamily(dataType: string): DatasourceTypeFamily | null {
+        const normalized = dataType.toLowerCase();
 
-        if (["int", "integer", "smallint", "tinyint"].includes(normalized)) {
-            return "int";
-        }
-
-        if (["numeric", "decimal", "float", "double", "real", "money", "smallmoney"].includes(normalized)) {
-            return "decimal";
-        }
-
-        if (["date"].includes(normalized)) {
-            return "date";
+        for (const [family, aliases] of Object.entries(DATASOURCE_TYPE_FAMILY_ALIASES) as Array<[DatasourceTypeFamily, string[]]>) {
+            if (aliases.includes(normalized)) {
+                return family;
+            }
         }
 
-        if (["time"].includes(normalized)) {
-            return "time";
+        if (normalized.includes("json")) {
+            return "json";
         }
 
-        if (["datetime", "datetime2", "timestamp", "timestamptz", "smalldatetime"].includes(normalized) || normalized.includes("date")) {
+        if (normalized.includes("date")) {
             return "datetime";
         }
 
-        if (["json", "jsonb", "simple-json", "simplejson"].includes(normalized) || normalized.includes("json")) {
-            return "json";
-        }
-
-        if (["uniqueidentifier", "uuid"].includes(normalized)) {
-            return "uuid";
-        }
+        return null;
+    }
 
-        if (["text", "ntext", "mediumtext", "longtext", "clob"].includes(normalized)) {
-            return "longText";
-        }
+    private toSolidFieldType(column: DatasourceIntrospectionColumn) {
+        const family = this.getDatasourceTypeFamily(column.dataType);
+        const charLength = column.characterMaximumLength ?? null;
 
-        if (["varchar", "nvarchar", "char", "nchar", "citext"].includes(normalized)) {
-            if (charLength !== null && charLength > 255) {
+        switch (family) {
+            case "boolean":
+                return "boolean";
+            case "bigint":
+                return "bigint";
+            case "int":
+                return "int";
+            case "numeric":
+            case "decimal":
+            case "float":
+                return "decimal";
+            case "date":
+                return "date";
+            case "time":
+                return "time";
+            case "datetime":
+            case "datetimeWithTimezone":
+                return "datetime";
+            case "json":
+            case "jsonb":
+                return "json";
+            case "uuid":
+                return "uuid";
+            case "mediumText":
+            case "longText":
                 return "longText";
-            }
+            case "shortText":
+            case "unicodeShortText":
+                if (charLength !== null && charLength > 255) {
+                    return "longText";
+                }
 
-            return "shortText";
+                return "shortText";
+            default:
+                return "shortText";
         }
-
-        return "shortText";
     }
 
     private toOrmFieldType(column: DatasourceIntrospectionColumn, datasourceType: string) {
-        const normalized = column.dataType.toLowerCase();
+        const family = this.getDatasourceTypeFamily(column.dataType);
         const normalizedDatasourceType = datasourceType.toLowerCase();
+        const ormType = family
+            ? ORM_TYPE_BY_DATASOURCE_FAMILY[normalizedDatasourceType]?.[family]
+            : undefined;
+
+        if (ormType) {
+            return ormType;
+        }
 
-        if (normalizedDatasourceType === "mssql") {
-            if (["bit", "bool", "boolean"].includes(normalized)) return "bit";
-            if (["bigint"].includes(normalized)) return "bigint";
-            if (["int", "integer", "smallint", "tinyint"].includes(normalized)) return "int";
-            if (["numeric"].includes(normalized)) return "numeric";
-            if (["decimal", "float", "double", "real", "money", "smallmoney"].includes(normalized)) return "decimal";
-            if (["date"].includes(normalized)) return "date";
-            if (["time"].includes(normalized)) return "time";
-            if (["datetime2"].includes(normalized)) return "datetime2";
-            if (["datetime", "smalldatetime", "timestamp"].includes(normalized) || normalized.includes("date")) return "datetime";
-            if (["json", "jsonb", "simple-json", "simplejson"].includes(normalized) || normalized.includes("json")) return "simple-json";
-            if (["uniqueidentifier", "uuid"].includes(normalized)) return "uniqueidentifier";
-            if (["text", "ntext", "mediumtext", "longtext", "clob"].includes(normalized)) return "text";
-            if (["nvarchar", "nchar"].includes(normalized)) return "nvarchar";
-            return "varchar";
-        }
-
-        if (normalizedDatasourceType === "mysql") {
-            if (["bigint"].includes(normalized)) return "int";
-            if (["int", "integer", "smallint", "tinyint"].includes(normalized)) return "int";
-            if (["decimal", "numeric"].includes(normalized)) return "decimal";
-            if (["float", "double", "real", "money", "smallmoney"].includes(normalized)) return "double";
-            if (["bit", "bool", "boolean"].includes(normalized)) return "boolean";
-            if (["date"].includes(normalized)) return "date";
-            if (["time"].includes(normalized)) return "time";
-            if (["datetime", "timestamp", "smalldatetime"].includes(normalized) || normalized.includes("date")) return "datetime";
-            if (["json", "jsonb", "simple-json", "simplejson"].includes(normalized) || normalized.includes("json")) return "json";
-            if (["mediumtext"].includes(normalized)) return "mediumtext";
-            if (["longtext", "text", "ntext", "clob"].includes(normalized)) return "longtext";
-            return "varchar";
-        }
-
-        if (["bigint"].includes(normalized)) return "bigint";
-        if (["int", "integer", "smallint", "tinyint"].includes(normalized)) return "integer";
-        if (["decimal", "numeric", "float", "double", "real", "money", "smallmoney"].includes(normalized)) return "decimal";
-        if (["bit", "bool", "boolean"].includes(normalized)) return "boolean";
-        if (["date"].includes(normalized)) return "date";
-        if (["time"].includes(normalized)) return "time";
-        if (["timestamptz"].includes(normalized)) return "timestamptz";
-        if (["datetime", "datetime2", "timestamp", "smalldatetime"].includes(normalized) || normalized.includes("date")) return "timestamp";
-        if (["jsonb"].includes(normalized)) return "jsonb";
-        if (["json", "simple-json", "simplejson"].includes(normalized) || normalized.includes("json")) return "json";
-        if (["text", "ntext", "mediumtext", "longtext", "clob"].includes(normalized)) return "text";
-        return "varchar";
+        return normalizedDatasourceType === "postgres" ? "varchar" : "varchar";
     }
 
     private toFieldName(columnName: string) {
@@ -1449,6 +1833,285 @@ export class DatasourceIntrospectionService {
         return `${datasourceName.toLowerCase()}::${tableName.toLowerCase()}`;
     }
 
+    private async syncTypeormDatasourceFile(moduleName: string, datasource: DatasourceRecord, singularName: string) {
+        const datasourceFilePath = path.resolve(process.cwd(), "src", `typeorm-${datasource.name}-datasource.ts`);
+        const entityClassName = classify(singularName);
+        const entityImportPath = `./${moduleName}/entities/${kebabCase(singularName)}.entity`;
+        const migrationGlob = `join(__dirname, './${moduleName}/migrations/${datasource.name}/*.{ts,js}')`;
+
+        const existingContent = await fs.readFile(datasourceFilePath, "utf8").catch(() => null);
+        if (!existingContent) {
+            const rendered = this.renderTypeormDatasourceTemplate({
+                datasource,
+                entityClassName,
+                entityImportPath,
+                migrationGlob,
+            });
+            await fs.writeFile(datasourceFilePath, rendered, "utf8");
+            return {
+                filePath: datasourceFilePath,
+                created: true,
+                updated: false,
+                entityRegistered: true,
+                migrationGlobRegistered: true,
+            };
+        }
+
+        const project = new Project({
+            skipAddingFilesFromTsConfig: true,
+            manipulationSettings: {
+                quoteKind: QuoteKind.Single,
+                indentationText: IndentationText.FourSpaces,
+                insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces: true,
+            },
+        });
+        const sourceFile = project.createSourceFile(datasourceFilePath, existingContent, { overwrite: true });
+
+        const entityImportDeclaration = sourceFile.getImportDeclarations().find((declaration) =>
+            declaration.getModuleSpecifierValue() === entityImportPath,
+        );
+        if (entityImportDeclaration) {
+            const alreadyImported = entityImportDeclaration.getNamedImports().some((namedImport) => namedImport.getName() === entityClassName);
+            if (!alreadyImported) {
+                entityImportDeclaration.addNamedImport(entityClassName);
+            }
+        } else {
+            sourceFile.addImportDeclaration({
+                moduleSpecifier: entityImportPath,
+                namedImports: [entityClassName],
+            });
+        }
+
+        const entitiesArray = sourceFile
+            .getVariableDeclarationOrThrow("entities")
+            .getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+        const entityAlreadyRegistered = this.arrayLiteralContainsValue(entitiesArray, entityClassName);
+        if (!entityAlreadyRegistered) {
+            entitiesArray.addElement(entityClassName);
+        }
+
+        const dataSourceOptions = this.getTypeormDatasourceOptions(sourceFile);
+        const migrationsArray = this.getObjectPropertyArrayLiteral(dataSourceOptions, "migrations");
+        const migrationAlreadyRegistered = this.arrayLiteralContainsValue(migrationsArray, migrationGlob);
+        if (!migrationAlreadyRegistered) {
+            migrationsArray.addElement(migrationGlob);
+        }
+
+        sourceFile.organizeImports();
+        sourceFile.formatText();
+
+        const nextContent = sourceFile.getFullText();
+        const updated = nextContent !== existingContent;
+        if (updated) {
+            await fs.writeFile(datasourceFilePath, nextContent, "utf8");
+        }
+
+        return {
+            filePath: datasourceFilePath,
+            created: false,
+            updated,
+            entityRegistered: true,
+            migrationGlobRegistered: true,
+        };
+    }
+
+    private async writeMigrationFile(migration: MappingPreviewRecord["migration"]) {
+        if (!migration.willGenerate || !migration.content || !migration.filePath) {
+            return false;
+        }
+
+        await fs.mkdir(path.dirname(migration.filePath), { recursive: true });
+        await fs.writeFile(migration.filePath, migration.content, "utf8");
+
+        const writtenContent = await fs.readFile(migration.filePath, "utf8").catch(() => null);
+        if (writtenContent !== migration.content) {
+            throw new BadRequestException(`Migration file could not be verified after writing: ${migration.filePath}`);
+        }
+
+        return true;
+    }
+
+    private renderTypeormDatasourceTemplate(input: {
+        datasource: DatasourceRecord;
+        entityClassName: string;
+        entityImportPath: string;
+        migrationGlob: string;
+    }) {
+        const { datasource, entityClassName, entityImportPath, migrationGlob } = input;
+        const envPrefix = datasource.envPrefix?.toUpperCase?.() || "DEFAULT";
+        const portFallback = datasource.type === "postgres" ? 5432 : datasource.type === "mysql" ? 3306 : 1433;
+        const project = new Project({
+            skipAddingFilesFromTsConfig: true,
+            manipulationSettings: {
+                quoteKind: QuoteKind.Single,
+                indentationText: IndentationText.FourSpaces,
+                insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces: true,
+            },
+        });
+        const sourceFile = project.createSourceFile("typeorm-template.ts", "", { overwrite: true });
+
+        sourceFile.addImportDeclaration({ moduleSpecifier: "reflect-metadata" });
+        sourceFile.addImportDeclaration({ moduleSpecifier: "path", namedImports: ["join"] });
+        sourceFile.addImportDeclaration({
+            moduleSpecifier: "dotenv",
+            namedImports: [{ name: "config", alias: "dotenvConfig" }],
+        });
+        sourceFile.addStatements("dotenvConfig({ path: join(__dirname, '../.env') });");
+        sourceFile.addStatements("");
+
+        sourceFile.addImportDeclaration({ moduleSpecifier: "typeorm", namedImports: ["DataSource"] });
+        sourceFile.addImportDeclaration({
+            moduleSpecifier: "@solidxai/core",
+            namespaceImport: "SolidCoreModuleExports",
+        });
+        sourceFile.addImportDeclaration({
+            moduleSpecifier: "@solidxai/core",
+            namedImports: ["getDynamicModuleNames", "parseBooleanEnv"],
+        });
+        sourceFile.addImportDeclaration({
+            moduleSpecifier: "typeorm",
+            namedImports: ["getMetadataArgsStorage"],
+        });
+        sourceFile.addImportDeclaration({
+            moduleSpecifier: "typeorm-naming-strategies",
+            namedImports: ["SnakeNamingStrategy"],
+        });
+        sourceFile.addImportDeclaration({
+            moduleSpecifier: entityImportPath,
+            namedImports: [entityClassName],
+        });
+
+        sourceFile.addFunction({
+            name: "getEntitiesFromExports",
+            parameters: [{ name: "exports", type: "Record<string, any>" }],
+            statements: (writer) => {
+                writer.writeLine("const metadataStorage = getMetadataArgsStorage();");
+                writer.writeLine("return Object.values(exports).filter((item) =>");
+                writer.indent(() => {
+                    writer.writeLine("metadataStorage.tables.some((table) => table.target === item),");
+                });
+                writer.write(");");
+            },
+        });
+
+        sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            declarations: [
+                {
+                    name: "coreEntities",
+                    initializer: "getEntitiesFromExports(SolidCoreModuleExports)",
+                },
+            ],
+        });
+        sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            declarations: [
+                {
+                    name: "dynamicModules",
+                    initializer: "getDynamicModuleNames()",
+                },
+            ],
+        });
+        sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            declarations: [
+                {
+                    name: "entities",
+                    initializer: `[\n    ...coreEntities,\n    ${entityClassName},\n]`,
+                },
+            ],
+        });
+        sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            declarations: [
+                {
+                    name: "logging",
+                    initializer: `parseBooleanEnv('${envPrefix}_DATABASE_LOGGING')`,
+                },
+            ],
+        });
+
+        sourceFile.addStatements("// IMPORTANT: synchronize must be false when using migrations");
+        sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            isExported: true,
+            declarations: [
+                {
+                    name: "DefaultDataSource",
+                    initializer: (writer) => {
+                        writer.write("new DataSource(");
+                        writer.inlineBlock(() => {
+                            writer.writeLine(`type: '${datasource.type}',`);
+                            writer.blankLine();
+                            writer.writeLine(`host: process.env.${envPrefix}_DATABASE_HOST,`);
+                            writer.writeLine(`port: +(process.env.${envPrefix}_DATABASE_PORT || ${portFallback}),`);
+                            writer.writeLine(`username: process.env.${envPrefix}_DATABASE_USER,`);
+                            writer.writeLine(`password: process.env.${envPrefix}_DATABASE_PASSWORD,`);
+                            writer.writeLine(`database: process.env.${envPrefix}_DATABASE_NAME,`);
+                            writer.blankLine();
+                            writer.writeLine("entities,");
+                            writer.writeLine("migrations: [");
+                            writer.indent(() => {
+                                writer.writeLine(`${migrationGlob},`);
+                            });
+                            writer.writeLine("],");
+                            writer.writeLine("synchronize: false,");
+                            writer.writeLine("logging,");
+                            writer.writeLine("namingStrategy: new SnakeNamingStrategy(),");
+                            if (datasource.type === "mssql") {
+                                writer.writeLine("options: {");
+                                writer.indent(() => {
+                                    writer.writeLine("encrypt: false,");
+                                    writer.writeLine("trustServerCertificate: true,");
+                                });
+                                writer.writeLine("},");
+                            }
+                        });
+                        writer.write(")");
+                    },
+                },
+            ],
+        });
+
+        sourceFile.organizeImports();
+        sourceFile.formatText();
+        return sourceFile.getFullText();
+    }
+
+    private arrayLiteralContainsValue(arrayLiteral: ArrayLiteralExpression, rawValue: string) {
+        const normalizedTarget = rawValue.replace(/\s+/g, "");
+        return arrayLiteral.getElements().some((element) => element.getText().replace(/\s+/g, "") === normalizedTarget);
+    }
+
+    private getTypeormDatasourceOptions(sourceFile: import("ts-morph").SourceFile) {
+        const defaultDataSourceDeclaration = sourceFile.getVariableDeclarationOrThrow("DefaultDataSource");
+        const initializer = defaultDataSourceDeclaration.getInitializer();
+        if (!initializer || !Node.isNewExpression(initializer)) {
+            throw new BadRequestException("Unable to locate DefaultDataSource initializer in datasource file.");
+        }
+
+        const options = initializer.getArguments()[0];
+        if (!options || !Node.isObjectLiteralExpression(options)) {
+            throw new BadRequestException("Unable to locate DefaultDataSource options object in datasource file.");
+        }
+
+        return options;
+    }
+
+    private getObjectPropertyArrayLiteral(objectLiteral: ObjectLiteralExpression, propertyName: string) {
+        const property = objectLiteral.getProperty(propertyName);
+        if (!property || !Node.isPropertyAssignment(property)) {
+            throw new BadRequestException(`Unable to locate "${propertyName}" property in datasource file.`);
+        }
+
+        const initializer = property.getInitializer();
+        if (!initializer || !Node.isArrayLiteralExpression(initializer)) {
+            throw new BadRequestException(`Unable to locate "${propertyName}" array in datasource file.`);
+        }
+
+        return initializer;
+    }
+
     private buildSynchronizeBlockedMessage(datasource: DatasourceRecord) {
         return `Datasource "${datasource.displayName}" has synchronize enabled. Set ${datasource.envPrefix}_DATABASE_SYNCHRONIZE=false before starting legacy table introspection.`;
     }