oak-db 3.3.14 → 4.0.0

package/lib/types/dbStore.d.ts

@@ -1,24 +1,16 @@
-import { Attribute, EntityDict, Index, OperateOption, OperationResult, StorageSchema, TxnOption } from 'oak-domain/lib/types';
+import { EntityDict, OperateOption, OperationResult, StorageSchema, TxnOption } from 'oak-domain/lib/types';
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
 import { AsyncContext, AsyncRowStore } from "oak-domain/lib/store/AsyncRowStore";
 import { CreateEntityOption } from "./Translator";
 import { AggregationResult, SelectOption } from "oak-domain/lib/types";
-export type Plan = {
-    newTables: Record<string, {
-        attributes: Record<string, Attribute>;
-    }>;
-    newIndexes: Record<string, Index<any>[]>;
-    updatedTables: Record<string, {
-        attributes: Record<string, Attribute & {
-            isNew: boolean;
-        }>;
-    }>;
-    updatedIndexes: Record<string, Index<any>[]>;
-};
+export type { Plan } from './migration';
+import type { MigrationPlanningOptions, Plan } from './migration';
 export interface DbStore<ED extends EntityDict & BaseEntityDict, Cxt extends AsyncContext<ED>> extends AsyncRowStore<ED, Cxt> {
     checkRelationAsync<T extends keyof ED, Cxt extends AsyncContext<ED>>(entity: T, operation: Omit<ED[T]['Operation'] | ED[T]['Selection'], 'id'>, context: Cxt): Promise<void>;
     connect: () => Promise<void>;
     disconnect: () => Promise<void>;
+    exec(script: string, txnId?: string): Promise<void>;
+    supportsTransactionalDdl(): boolean;
     initialize(options: CreateEntityOption): Promise<void>;
     aggregate<T extends keyof ED, OP extends SelectOption>(entity: T, aggregation: ED[T]['Aggregation'], context: Cxt, option: OP): Promise<AggregationResult<ED[T]['Schema']>>;
     operate<T extends keyof ED>(entity: T, operation: ED[T]['Operation'], context: Cxt, option: OperateOption): Promise<OperationResult<ED>>;
@@ -28,6 +20,6 @@ export interface DbStore<ED extends EntityDict & BaseEntityDict, Cxt extends Asy
     commit(txnId: string): Promise<void>;
     rollback(txnId: string): Promise<void>;
     readSchema(): Promise<StorageSchema<ED>>;
-    makeUpgradePlan(): Promise<Plan>;
-    diffSchema(schemaOld: StorageSchema<any>, schemaNew: StorageSchema<any>): Plan;
+    makeUpgradePlan(options?: MigrationPlanningOptions): Promise<Plan>;
+    diffSchema(schemaOld: StorageSchema<ED>, schemaNew: StorageSchema<ED>, options?: MigrationPlanningOptions): Plan;
 }

package/lib/types/migration.d.ts

@@ -0,0 +1,251 @@
+import { Attribute, EntityDict, GeneralEntityShape, Index, StorageDesc, StorageSchema } from 'oak-domain/lib/types';
+export type MigrationEntityDict = EntityDict;
+export type MigrationEntityKey = keyof MigrationEntityDict & string;
+export type MigrationSchema<ED extends MigrationEntityDict = MigrationEntityDict> = StorageSchema<ED>;
+export type MigrationTableDef<SH extends GeneralEntityShape = GeneralEntityShape> = StorageDesc<SH>;
+export type MigrationIndex<SH extends GeneralEntityShape = GeneralEntityShape> = Index<SH>;
+export interface MigrationIndexMetadata {
+    __originName?: string;
+    __originNames?: string[];
+}
+export type MigrationIndexWithOrigin = MigrationIndex & MigrationIndexMetadata;
+export type MigrationWarningLevel = 'info' | 'warning';
+export type MigrationWarningCode = 'rename-candidate' | 'manual-column-change' | 'manual-index-change' | 'manual-foreign-key-change' | 'manual-enum-change' | 'manual-constraint-change' | 'large-table-index-change';
+export interface MigrationWarning {
+    code: MigrationWarningCode;
+    level: MigrationWarningLevel;
+    message: string;
+    table?: string;
+    column?: string;
+    sql?: string[];
+}
+export interface RenameCandidate {
+    table: string;
+    from: string;
+    to: string;
+    reason: string;
+    sql: string[];
+}
+export interface ForeignKeyDef {
+    name: string;
+    column: string;
+    refTable: string;
+    refColumn: string;
+    onDelete: 'cascade' | 'set null' | 'no action';
+}
+export interface TableStats {
+    rowCount?: number;
+    approximate?: boolean;
+}
+export interface SchemaInspectionResult<ED extends MigrationEntityDict = MigrationEntityDict> {
+    schema: MigrationSchema<ED>;
+    tableStats: Record<string, TableStats>;
+}
+export interface MigrationPlanningOptions {
+    currentTableStats?: Record<string, TableStats>;
+    largeTableRowThreshold?: number;
+    compareForeignKeys?: boolean;
+}
+export interface IndexPlanContext {
+    isNewTable: boolean;
+    tableStats?: TableStats;
+    largeTableRowThreshold: number;
+}
+export interface MigrationPlanSummary {
+    newTables: number;
+    removedTables: number;
+    addedColumns: number;
+    removedColumns: number;
+    changedColumns: number;
+    addedIndexes: number;
+    removedIndexes: number;
+    changedIndexes: number;
+    addedForeignKeys: number;
+    removedForeignKeys: number;
+    changedForeignKeys: number;
+    manualActions: number;
+    onlineActions: number;
+    largeTableIndexes: number;
+}
+export type MigrationSqlCategory = 'prepareSql' | 'forwardSql' | 'onlineSql' | 'manualSql' | 'backwardSql';
+export interface MigrationSqlByCategory {
+    prepareSql: string[];
+    forwardSql: string[];
+    onlineSql: string[];
+    manualSql: string[];
+    backwardSql: string[];
+}
+export interface MigrationTableColumnAddition {
+    name: string;
+    categories: MigrationSqlCategory[];
+    reason?: string;
+    definition: AttributeSnapshot;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableColumnRemoval {
+    name: string;
+    categories: MigrationSqlCategory[];
+    definition: AttributeSnapshot;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableColumnChange {
+    name: string;
+    categories: MigrationSqlCategory[];
+    reason?: string;
+    before: AttributeSnapshot;
+    after: AttributeSnapshot;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableColumnRename {
+    from: string;
+    to: string;
+    categories: MigrationSqlCategory[];
+    reason: string;
+    before: AttributeSnapshot;
+    after: AttributeSnapshot;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableIndexAddition {
+    name: string;
+    categories: MigrationSqlCategory[];
+    definition: IndexSnapshot;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableIndexRemoval {
+    name: string;
+    categories: MigrationSqlCategory[];
+    definition: IndexSnapshot;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableIndexChange {
+    name: string;
+    categories: MigrationSqlCategory[];
+    before: IndexSnapshot;
+    after: IndexSnapshot;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableIndexRename {
+    from: string;
+    to: string;
+    categories: MigrationSqlCategory[];
+    before: IndexSnapshot;
+    after: IndexSnapshot;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableForeignKeyAddition {
+    name: string;
+    categories: MigrationSqlCategory[];
+    definition: ForeignKeyDef;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableForeignKeyRemoval {
+    name: string;
+    categories: MigrationSqlCategory[];
+    definition: ForeignKeyDef;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableForeignKeyChange {
+    name: string;
+    categories: MigrationSqlCategory[];
+    before?: ForeignKeyDef;
+    after?: ForeignKeyDef;
+    sql: MigrationSqlByCategory;
+}
+export interface MigrationTableChange {
+    entity: string;
+    table: string;
+    lifecycle: 'create' | 'alter' | 'drop';
+    summary: MigrationPlanSummary;
+    sql: MigrationSqlByCategory;
+    columns: {
+        added: MigrationTableColumnAddition[];
+        removed: MigrationTableColumnRemoval[];
+        changed: MigrationTableColumnChange[];
+        renamed: MigrationTableColumnRename[];
+    };
+    indexes: {
+        added: MigrationTableIndexAddition[];
+        removed: MigrationTableIndexRemoval[];
+        changed: MigrationTableIndexChange[];
+        renamed: MigrationTableIndexRename[];
+    };
+    foreignKeys: {
+        added: MigrationTableForeignKeyAddition[];
+        removed: MigrationTableForeignKeyRemoval[];
+        changed: MigrationTableForeignKeyChange[];
+    };
+    warnings: MigrationWarning[];
+    renameCandidates: RenameCandidate[];
+}
+export interface MigrationPlan<ED extends MigrationEntityDict = MigrationEntityDict> {
+    currentSchema: MigrationSchema<ED>;
+    targetSchema: MigrationSchema<ED>;
+    prepareSql: string[];
+    forwardSql: string[];
+    onlineSql: string[];
+    manualSql: string[];
+    backwardSql: string[];
+    warnings: MigrationWarning[];
+    renameCandidates: RenameCandidate[];
+    summary: MigrationPlanSummary;
+    tableChanges: MigrationTableChange[];
+}
+export type Plan<ED extends MigrationEntityDict = MigrationEntityDict> = MigrationPlan<ED>;
+export interface MigrationChangePlan {
+    prepareSql?: string[];
+    forwardSql?: string[];
+    deferredForwardSql?: string[];
+    onlineSql?: string[];
+    manualSql?: string[];
+    backwardSql?: string[];
+    warnings?: MigrationWarning[];
+    renameCandidates?: RenameCandidate[];
+    summary?: Partial<MigrationPlanSummary>;
+}
+export interface AttributeSnapshot {
+    type: string;
+    params?: Record<string, number>;
+    enumeration?: string[];
+    ref?: string | string[];
+    onRefDelete?: 'delete' | 'setNull' | 'ignore';
+    default?: string | number | boolean;
+    notNull: boolean;
+    unique: boolean;
+    sequence: boolean;
+}
+export interface IndexSnapshot {
+    name: string;
+    attributes: Array<{
+        name: string;
+        direction?: 'ASC' | 'DESC';
+        size?: number;
+    }>;
+    config: {
+        unique: boolean;
+        type: 'btree' | 'hash' | 'spatial' | 'fulltext';
+        parser?: string;
+        tsConfig?: string | string[];
+        chineseParser?: string;
+    };
+}
+export interface AttributeChangeClassification {
+    mode: 'none' | 'forward' | 'manual';
+    reason?: string;
+    enumAppendOnly?: true;
+}
+export interface SchemaMigrationAdapter<ED extends MigrationEntityDict = MigrationEntityDict> {
+    readonly dialect: 'mysql' | 'postgresql';
+    normalizeIdentifier(name: string): string;
+    getTableName(table: string, tableDef?: {
+        storageName?: string;
+    }): string;
+    buildPrepareSql(currentSchema: MigrationSchema<ED>, targetSchema: MigrationSchema<ED>): string[];
+    buildNewTablePlan(table: string, tableDef: MigrationTableDef): MigrationChangePlan;
+    buildDropTablePlan(tableName: string): MigrationChangePlan;
+    buildRenamePlan(tableName: string, from: string, to: string, oldAttr: Attribute, newAttr: Attribute): MigrationChangePlan;
+    buildColumnPlan(tableName: string, column: string, oldAttr: Attribute | undefined, newAttr: Attribute | undefined, classification: AttributeChangeClassification): MigrationChangePlan;
+    buildIndexPlan(tableName: string, table: string, oldIndex: MigrationIndexWithOrigin | undefined, newIndex: MigrationIndexWithOrigin | undefined, context: IndexPlanContext): MigrationChangePlan;
+    buildRenameIndexPlan(tableName: string, table: string, oldIndex: MigrationIndexWithOrigin, newIndex: MigrationIndexWithOrigin, context: IndexPlanContext): MigrationChangePlan;
+    buildForeignKeyPlan(tableName: string, oldForeignKey: ForeignKeyDef | undefined, newForeignKey: ForeignKeyDef | undefined, isNewTable: boolean): MigrationChangePlan;
+    getForeignKeys(table: string, tableDef: MigrationTableDef, fullSchema: MigrationSchema<ED>): Record<string, ForeignKeyDef>;
+}

package/lib/types/migration.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/utils/indexInspection.d.ts

@@ -0,0 +1,4 @@
+import { MigrationIndexWithOrigin } from '../types/migration';
+export declare function getIndexOriginNames(index: MigrationIndexWithOrigin): string[];
+export declare function mergeIndexOriginName(index: MigrationIndexWithOrigin, originName: string): void;
+export declare function areEquivalentInspectedIndexes(left: MigrationIndexWithOrigin, right: MigrationIndexWithOrigin): boolean;

package/lib/utils/indexInspection.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIndexOriginNames = getIndexOriginNames;
+exports.mergeIndexOriginName = mergeIndexOriginName;
+exports.areEquivalentInspectedIndexes = areEquivalentInspectedIndexes;
+function getIndexOriginNames(index) {
+    return index.__originNames?.length
+        ? [...index.__originNames]
+        : (index.__originName
+            ? [index.__originName]
+            : [index.name]);
+}
+function mergeIndexOriginName(index, originName) {
+    const originNames = new Set();
+    if (index.__originName) {
+        originNames.add(index.__originName);
+    }
+    (index.__originNames || []).forEach((name) => originNames.add(name));
+    originNames.add(originName);
+    const merged = Array.from(originNames);
+    delete index.__originName;
+    index.__originNames = merged;
+}
+function areEquivalentInspectedIndexes(left, right) {
+    return JSON.stringify({
+        attributes: left.attributes,
+        config: left.config || {},
+    }) === JSON.stringify({
+        attributes: right.attributes,
+        config: right.config || {},
+    });
+}

package/lib/utils/indexName.d.ts

@@ -0,0 +1,15 @@
+export declare function buildEntityIndexPrefix(name: string): string;
+export declare function shortenIdentifierWithHash(identifier: string, maxLength: number): string;
+export interface CompactIndexNameOptions {
+    entityName: string;
+    tableName?: string;
+    logicalName: string;
+    suffix?: string;
+    maxLength: number;
+}
+export interface LegacyIndexNameOptions extends CompactIndexNameOptions {
+    serverTruncatesWhenOverflow?: boolean;
+}
+export declare function buildCompactPhysicalIndexName(options: CompactIndexNameOptions): string;
+export declare function buildLegacyPhysicalIndexNames(options: LegacyIndexNameOptions): string[];
+export declare function matchesPhysicalIndexName(actualName: string, options: LegacyIndexNameOptions): boolean;

package/lib/utils/indexName.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEntityIndexPrefix = buildEntityIndexPrefix;
+exports.shortenIdentifierWithHash = shortenIdentifierWithHash;
+exports.buildCompactPhysicalIndexName = buildCompactPhysicalIndexName;
+exports.buildLegacyPhysicalIndexNames = buildLegacyPhysicalIndexNames;
+exports.matchesPhysicalIndexName = matchesPhysicalIndexName;
+const crypto_1 = require("crypto");
+function uniqueNonEmpty(values) {
+    return Array.from(new Set(values.filter(Boolean)));
+}
+function splitIdentifier(name) {
+    const normalized = name
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_\-\s]+/g, ' ')
+        .trim();
+    return normalized ? normalized.split(/\s+/).filter(Boolean) : [];
+}
+function stripLogicalIndexPrefix(logicalName, prefixes) {
+    for (const prefix of uniqueNonEmpty(prefixes)) {
+        if (logicalName.startsWith(`${prefix}_`)) {
+            return logicalName.slice(prefix.length + 1);
+        }
+    }
+    return logicalName;
+}
+function buildEntityIndexPrefix(name) {
+    const parts = splitIdentifier(name);
+    if (parts.length === 0) {
+        return 'i';
+    }
+    const [first, ...rest] = parts;
+    return `${first.slice(0, Math.min(3, first.length)).toLowerCase()}${rest.map((part) => part[0].toUpperCase()).join('')}`;
+}
+function shortenIdentifierWithHash(identifier, maxLength) {
+    if (identifier.length <= maxLength) {
+        return identifier;
+    }
+    const hash = (0, crypto_1.createHash)('sha1')
+        .update(identifier)
+        .digest('hex')
+        .slice(0, 8);
+    const prefixLength = Math.max(1, maxLength - hash.length - 1);
+    return `${identifier.slice(0, prefixLength)}_${hash}`;
+}
+function buildCompactPhysicalIndexName(options) {
+    const { entityName, tableName, logicalName, suffix = '', maxLength, } = options;
+    const compactPrefix = buildEntityIndexPrefix(entityName || tableName || logicalName);
+    const baseName = stripLogicalIndexPrefix(logicalName, uniqueNonEmpty([entityName, tableName]));
+    return shortenIdentifierWithHash(`${compactPrefix}_${baseName}${suffix}`, maxLength);
+}
+function buildLegacyPhysicalIndexNames(options) {
+    const { entityName, tableName, logicalName, suffix = '', maxLength, serverTruncatesWhenOverflow, } = options;
+    const names = new Set();
+    const prefixedBases = uniqueNonEmpty([entityName, tableName]);
+    names.add(`${logicalName}${suffix}`);
+    prefixedBases.forEach((base) => {
+        names.add(`${base}_${logicalName}${suffix}`);
+        names.add(logicalName.startsWith(`${base}_`)
+            ? `${logicalName}${suffix}`
+            : `${base}_${logicalName}${suffix}`);
+    });
+    names.add(buildCompactPhysicalIndexName(options));
+    const resolved = new Set();
+    names.forEach((name) => {
+        resolved.add(name);
+        if (serverTruncatesWhenOverflow && name.length > maxLength) {
+            resolved.add(name.slice(0, maxLength));
+        }
+    });
+    return Array.from(resolved);
+}
+function matchesPhysicalIndexName(actualName, options) {
+    return buildLegacyPhysicalIndexNames(options).includes(actualName);
+}

package/lib/utils/inspection.d.ts

@@ -0,0 +1,13 @@
+import { Attribute } from 'oak-domain/lib/types';
+import { MigrationEntityDict, MigrationSchema, MigrationTableDef } from '../types/migration';
+export interface InspectionTypeHintRule {
+    actualTypes: string[];
+    semanticTypes: string[];
+}
+export declare function buildTargetTableHintMap<ED extends MigrationEntityDict>(schema: MigrationSchema<ED>): Map<string, {
+    key: string;
+    tableDef: MigrationTableDef;
+}>;
+export declare function applyInspectionAttributeHint(attr: Attribute, hint: Attribute | undefined, rules: InspectionTypeHintRule[]): Attribute;
+export declare function applyOakManagedAttributeFallback(attr: Attribute, columnName: string, hint?: Attribute): Attribute;
+export declare function isOakManagedTable(attributes: Record<string, Attribute>, hasTableHint: boolean): boolean;

package/lib/utils/inspection.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTargetTableHintMap = buildTargetTableHintMap;
+exports.applyInspectionAttributeHint = applyInspectionAttributeHint;
+exports.applyOakManagedAttributeFallback = applyOakManagedAttributeFallback;
+exports.isOakManagedTable = isOakManagedTable;
+const oakManagedColumns = ['id', '$$createAt$$', '$$updateAt$$', '$$deleteAt$$'];
+const oakDatetimeColumns = new Set(['$$createAt$$', '$$updateAt$$', '$$deleteAt$$']);
+function normalizeTypeName(type) {
+    return String(type).toLowerCase();
+}
+function buildTargetTableHintMap(schema) {
+    const tableHints = new Map();
+    Object.keys(schema).forEach((table) => {
+        const tableDef = schema[table];
+        tableHints.set(tableDef.storageName || table, {
+            key: table,
+            tableDef,
+        });
+    });
+    return tableHints;
+}
+function applyInspectionAttributeHint(attr, hint, rules) {
+    if (!hint) {
+        return attr;
+    }
+    const actualType = normalizeTypeName(attr.type);
+    const semanticType = normalizeTypeName(hint.type);
+    const matchedRule = rules.find((rule) => rule.actualTypes.includes(actualType)
+        && rule.semanticTypes.includes(semanticType));
+    if (!matchedRule) {
+        return attr;
+    }
+    return {
+        ...attr,
+        type: hint.type,
+    };
+}
+function applyOakManagedAttributeFallback(attr, columnName, hint) {
+    if (hint) {
+        return attr;
+    }
+    if (attr.type === 'bigint' && oakDatetimeColumns.has(columnName)) {
+        return {
+            ...attr,
+            type: 'datetime',
+        };
+    }
+    return attr;
+}
+function isOakManagedTable(attributes, hasTableHint) {
+    if (hasTableHint) {
+        return true;
+    }
+    return oakManagedColumns.every((column) => !!attributes[column]);
+}

package/package.json

@@ -1,7 +1,10 @@
 {
 	"name": "oak-db",
-	"version": "3.3.14",
+	"version": "4.0.0",
 	"description": "oak-db",
+	"oak": {
+		"package": true
+	},
 	"main": "lib/index",
 	"author": {
 		"name": "XuChang"
@@ -18,7 +21,7 @@
 		"lodash": "^4.17.21",
 		"mysql": "^2.18.1",
 		"mysql2": "^2.3.3",
-		"oak-domain": "^5.1.36",
+		"oak-domain": "file:../oak-domain",
 		"pg": "^8.16.3",
 		"uuid": "^8.3.2"
 	},