oak-db 3.3.13 → 4.0.0

package/lib/PostgreSQL/prepare.d.ts

@@ -0,0 +1,2 @@
+import { MigrationSchema } from '../types/migration';
+export declare function buildPostgreSqlPrepareSql(currentSchema: MigrationSchema, targetSchema: MigrationSchema): string[];

package/lib/PostgreSQL/prepare.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPostgreSqlPrepareSql = buildPostgreSqlPrepareSql;
+const textSearchConfigRegistry = {
+    chinese: {
+        getRequirement(parser = 'zhparser') {
+            return {
+                extension: parser,
+                bootstrapSql: [`DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_catalog.pg_ts_config WHERE cfgname = 'chinese'
+    ) THEN
+        CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = ${parser});
+        ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
+    END IF;
+END $$;`],
+            };
+        },
+    },
+};
+function collectPostgreSqlSchemaFeatures(schema) {
+    const extensions = new Set();
+    const textSearchConfigs = new Map();
+    Object.values(schema).forEach((tableDef) => {
+        Object.values(tableDef.attributes || {}).forEach((attr) => {
+            if (attr.type === 'geometry' || attr.type === 'geography') {
+                extensions.add('postgis');
+            }
+        });
+        (tableDef.indexes || []).forEach((index) => {
+            const tsConfigs = Array.isArray(index.config?.tsConfig)
+                ? index.config.tsConfig
+                : [index.config?.tsConfig];
+            tsConfigs.filter(Boolean).forEach((tsConfig) => {
+                const entry = textSearchConfigRegistry[tsConfig];
+                if (!entry) {
+                    return;
+                }
+                const requirement = entry.getRequirement(index.config?.chineseParser);
+                if (requirement.extension) {
+                    extensions.add(requirement.extension);
+                }
+                textSearchConfigs.set(tsConfig, requirement);
+            });
+        });
+    });
+    return {
+        extensions,
+        textSearchConfigs,
+    };
+}
+function buildPostgreSqlPrepareSql(currentSchema, targetSchema) {
+    const sqls = [];
+    const currentFeatures = collectPostgreSqlSchemaFeatures(currentSchema);
+    const targetFeatures = collectPostgreSqlSchemaFeatures(targetSchema);
+    targetFeatures.extensions.forEach((extension) => {
+        if (!currentFeatures.extensions.has(extension)) {
+            sqls.push(`CREATE EXTENSION IF NOT EXISTS ${extension};`);
+        }
+    });
+    targetFeatures.textSearchConfigs.forEach((requirement, configName) => {
+        if (currentFeatures.textSearchConfigs.has(configName)) {
+            return;
+        }
+        sqls.push(...requirement.bootstrapSql);
+    });
+    return sqls;
+}

package/lib/PostgreSQL/store.d.ts

@@ -8,12 +8,14 @@ import { AsyncContext } from 'oak-domain/lib/store/AsyncRowStore';
 import { SyncContext } from 'oak-domain/lib/store/SyncRowStore';
 import { CreateEntityOption } from '../types/Translator';
 import { DbStore, Plan } from '../types/dbStore';
+import { MigrationPlanningOptions } from '../types/migration';
 export declare class PostgreSQLStore<ED extends EntityDict & BaseEntityDict, Cxt extends AsyncContext<ED>> extends CascadeStore<ED> implements DbStore<ED, Cxt> {
     protected countAbjointRow<T extends keyof ED, OP extends SelectOption, Cxt extends SyncContext<ED>>(entity: T, selection: Pick<ED[T]['Selection'], 'filter' | 'count'>, context: Cxt, option: OP): number;
     protected aggregateAbjointRowSync<T extends keyof ED, OP extends SelectOption, Cxt extends SyncContext<ED>>(entity: T, aggregation: ED[T]['Aggregation'], context: Cxt, option: OP): AggregationResult<ED[T]['Schema']>;
     protected selectAbjointRow<T extends keyof ED, OP extends SelectOption>(entity: T, selection: ED[T]['Selection'], context: SyncContext<ED>, option: OP): Partial<ED[T]['Schema']>[];
     protected updateAbjointRow<T extends keyof ED, OP extends OperateOption>(entity: T, operation: ED[T]['Operation'], context: SyncContext<ED>, option: OP): number;
     exec(script: string, txnId?: string): Promise<void>;
+    supportsTransactionalDdl(): boolean;
     connector: PostgreSQLConnector;
     translator: PostgreSQLTranslator<ED>;
     constructor(storageSchema: StorageSchema<ED>, configuration: PostgreSQLConfiguration);
@@ -22,9 +24,13 @@ export declare class PostgreSQLStore<ED extends EntityDict & BaseEntityDict, Cxt
     aggregate<T extends keyof ED, OP extends SelectOption>(entity: T, aggregation: ED[T]['Aggregation'], context: Cxt, option: OP): Promise<AggregationResult<ED[T]['Schema']>>;
     protected supportManyToOneJoin(): boolean;
     protected supportMultipleCreate(): boolean;
+    protected supportUpdateReturning(): boolean;
     private formResult;
+    private lockSelectedRows;
     protected selectAbjointRowAsync<T extends keyof ED>(entity: T, selection: ED[T]['Selection'], context: AsyncContext<ED>, option?: PostgreSQLSelectOption): Promise<Partial<ED[T]['Schema']>[]>;
     protected updateAbjointRowAsync<T extends keyof ED>(entity: T, operation: ED[T]['Operation'], context: AsyncContext<ED>, option?: PostgreSQLOperateOption): Promise<number>;
+    protected updateAbjointRowReturningSync<T extends keyof ED>(entity: T, operation: ED[T]['Operation'], context: AsyncContext<ED>, returning: Record<string, any>, option?: PostgreSQLOperateOption): [number, Partial<ED[T]['Schema']>[]];
+    protected updateAbjointRowReturningAsync<T extends keyof ED>(entity: T, operation: ED[T]['Operation'], context: AsyncContext<ED>, returning: Record<string, any>, option?: PostgreSQLOperateOption): Promise<[number, Partial<ED[T]['Schema']>[]]>;
     operate<T extends keyof ED>(entity: T, operation: ED[T]['Operation'], context: Cxt, option: OperateOption): Promise<OperationResult<ED>>;
     select<T extends keyof ED>(entity: T, selection: ED[T]['Selection'], context: Cxt, option: SelectOption): Promise<Partial<ED[T]['Schema']>[]>;
     protected countAbjointRowAsync<T extends keyof ED>(entity: T, selection: Pick<ED[T]['Selection'], 'filter' | 'count'>, context: AsyncContext<ED>, option: SelectOption): Promise<number>;
@@ -34,17 +40,25 @@ export declare class PostgreSQLStore<ED extends EntityDict & BaseEntityDict, Cxt
     rollback(txnId: string): Promise<void>;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
+    private shouldLogInitializeProgress;
+    private isFullManagedReset;
+    private runInitializeTransaction;
+    private ensureChineseTextSearchConfiguration;
+    private createManagedSchema;
+    private applyForeignKeysFromPlan;
+    private applyDeclaredForeignKeys;
+    private applyMissingForeignKeys;
     initialize(option: CreateEntityOption): Promise<void>;
     readSchema(): Promise<StorageSchema<ED>>;
     /**
      * 根据载入的dataSchema，和数据库中原来的schema，决定如何来upgrade
      * 制订出来的plan分为两阶段：增加阶段和削减阶段，在两个阶段之间，由用户来修正数据
      */
-    makeUpgradePlan(): Promise<Plan>;
+    makeUpgradePlan(options?: MigrationPlanningOptions): Promise<Plan<ED>>;
     /**
      * 比较两个schema的不同，这里计算的是new对old的增量
      * @param schemaOld
      * @param schemaNew
      */
-    diffSchema(schemaOld: StorageSchema<any>, schemaNew: StorageSchema<any>): Plan;
+    diffSchema(schemaOld: StorageSchema<ED>, schemaNew: StorageSchema<ED>, options?: MigrationPlanningOptions): Plan<ED>;
 }

package/lib/PostgreSQL/store.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgreSQLStore = void 0;
 const tslib_1 = require("tslib");
+const types_1 = require("oak-domain/lib/types");
 const CascadeStore_1 = require("oak-domain/lib/store/CascadeStore");
 const connector_1 = require("./connector");
 const translator_1 = require("./translator");
@@ -70,6 +71,9 @@ class PostgreSQLStore extends CascadeStore_1.CascadeStore {
     async exec(script, txnId) {
         await this.connector.exec(script, txnId);
     }
+    supportsTransactionalDdl() {
+        return true;
+    }
     connector;
     translator;
     constructor(storageSchema, configuration) {
@@ -94,6 +98,9 @@ class PostgreSQLStore extends CascadeStore_1.CascadeStore {
     supportMultipleCreate() {
         return true;
     }
+    supportUpdateReturning() {
+        return true;
+    }
     formResult(entity, result) {
         const schema = this.getSchema();
         function resolveAttribute(entity2, r, attr, value) {
@@ -272,10 +279,34 @@ class PostgreSQLStore extends CascadeStore_1.CascadeStore {
         }
         return formSingleRow(result);
     }
+    async lockSelectedRows(entity, rows, context, forUpdate) {
+        // PostgreSQL 不能在 outer join 的 nullable side 上直接 FOR UPDATE，
+        // 因此先完成主查询，再按根表主键补锁，保持上层 forUpdate 用法不变。
+        if (rows.length === 0) {
+            return;
+        }
+        const ids = Array.from(new Set(rows.map((row) => {
+            const id = row[types_1.PrimaryKeyAttribute];
+            (0, assert_1.default)(typeof id === 'string' && id.length > 0, `对象${String(entity)}取数据时未能获取主键，无法完成 for update 锁定`);
+            return id;
+        })));
+        const tableName = this.translator.quoteIdentifier(this.getSchema()[entity].storageName || entity);
+        const idName = this.translator.quoteIdentifier(types_1.PrimaryKeyAttribute);
+        const inClause = ids.map((id) => this.translator.escapeStringValue(id)).join(', ');
+        let sql = `SELECT ${idName} FROM ${tableName} WHERE ${idName} IN (${inClause}) FOR UPDATE`;
+        if (typeof forUpdate === 'string') {
+            sql += ` ${forUpdate}`;
+        }
+        await this.connector.exec(sql, context.getCurrentTxnId());
+    }
     async selectAbjointRowAsync(entity, selection, context, option) {
         const sql = this.translator.translateSelect(entity, selection, option);
         const result = await this.connector.exec(sql, context.getCurrentTxnId());
-        return this.formResult(entity, result[0]);
+        const rows = this.formResult(entity, result[0]);
+        if (option?.forUpdate) {
+            await this.lockSelectedRows(entity, rows, context, option.forUpdate);
+        }
+        return rows;
     }
     async updateAbjointRowAsync(entity, operation, context, option) {
         const { translator, connector } = this;
@@ -302,6 +333,33 @@ class PostgreSQLStore extends CascadeStore_1.CascadeStore {
             }
         }
     }
+    updateAbjointRowReturningSync(entity, operation, context, returning, option) {
+        throw new Error('PostgreSQL store 不支持同步更新数据');
+    }
+    async updateAbjointRowReturningAsync(entity, operation, context, returning, option) {
+        const { translator, connector } = this;
+        const { action } = operation;
+        const txn = context.getCurrentTxnId();
+        switch (action) {
+            case 'create': {
+                const { data } = operation;
+                const sql = translator.translateInsert(entity, data instanceof Array ? data : [data]);
+                const result = await connector.exec(sql, txn);
+                return [result[1].rowCount || 0, []];
+            }
+            case 'remove': {
+                const sql = translator.translateRemove(entity, operation, Object.assign({}, option, { returning }));
+                const result = await connector.exec(sql, txn);
+                return [result[1].rowCount || 0, this.formResult(entity, result[0])];
+            }
+            default: {
+                (0, assert_1.default)(!['select', 'download', 'stat'].includes(action));
+                const sql = translator.translateUpdate(entity, operation, Object.assign({}, option, { returning }));
+                const result = await connector.exec(sql, txn);
+                return [result[1].rowCount || 0, this.formResult(entity, result[0])];
+            }
+        }
+    }
     async operate(entity, operation, context, option) {
         const { action } = operation;
         (0, assert_1.default)(!['select', 'download', 'stat'].includes(action), '不支持使用 select operation');
@@ -335,75 +393,159 @@ class PostgreSQLStore extends CascadeStore_1.CascadeStore {
     async disconnect() {
         await this.connector.disconnect();
     }
-    async initialize(option) {
-        // PG的DDL支持事务，所以这里直接用一个事务包裹所有的初始化操作
-        const txn = await this.connector.startTransaction({
-            isolationLevel: 'serializable',
-        });
+    shouldLogInitializeProgress(current, total, step) {
+        return total <= step || current === 1 || current === total || current % step === 0;
+    }
+    isFullManagedReset(option) {
+        return (option?.ifExists || 'drop') === 'drop';
+    }
+    async runInitializeTransaction(executor) {
+        // PostgreSQL initialize 不能再把整套 schema DDL 塞进一个大事务。
+        // 大 schema 下 DDL 锁会一直累积到 COMMIT，最终触发
+        // “out of shared memory / max_locks_per_transaction”。
+        // 这里把事务边界收敛到“单个初始化单元”（文本检索配置 / 单个实体）；
+        // 既保留局部原子性，也让锁能及时释放。
+        const txn = await this.connector.startTransaction();
         try {
-            const schema = this.getSchema();
-            let hasGeoType = false;
-            let hasChineseTsConfig = false;
-            for (const entity in schema) {
-                const { attributes, indexes } = schema[entity];
-                for (const attr in attributes) {
-                    const { type } = attributes[attr];
-                    if (type === 'geometry') {
-                        hasGeoType = true;
-                    }
-                }
-                for (const index of indexes || []) {
-                    if (index.config?.tsConfig === 'chinese' || index.config?.tsConfig?.includes('chinese')) {
-                        hasChineseTsConfig = true;
-                    }
-                }
-            }
-            if (hasGeoType) {
-                console.log('Initializing PostGIS extension for geometry support...');
-                await this.connector.exec('CREATE EXTENSION IF NOT EXISTS postgis;');
-            }
-            if (hasChineseTsConfig) {
-                console.log('Initializing Chinese text search configuration...');
-                const checkChineseConfigSql = `
-            SELECT COUNT(*) as cnt
-            FROM pg_catalog.pg_ts_config
-            WHERE cfgname = 'chinese';
+            await executor(txn);
+            await this.connector.commitTransaction(txn);
+        }
+        catch (error) {
+            await this.connector.rollbackTransaction(txn);
+            throw error;
+        }
+    }
+    async ensureChineseTextSearchConfiguration(hasChineseTsConfig, chineseParser) {
+        if (!hasChineseTsConfig) {
+            return;
+        }
+        await this.runInitializeTransaction(async (txn) => {
+            console.log('Initializing Chinese text search configuration...');
+            const checkChineseConfigSql = `
+                SELECT COUNT(*) as cnt
+                FROM pg_catalog.pg_ts_config
+                WHERE cfgname = 'chinese';
             `;
-                const result = await this.connector.exec(checkChineseConfigSql);
-                const count = parseInt(result[0][0]?.cnt || '0', 10);
-                if (count === 0) {
-                    const createChineseConfigSql = `
-                CREATE EXTENSION IF NOT EXISTS zhparser;
-                CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);
-                ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
+            const result = await this.connector.exec(checkChineseConfigSql, txn);
+            const count = parseInt(result[0][0]?.cnt || '0', 10);
+            if (count === 0) {
+                const createChineseConfigSql = `
+                    CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = ${chineseParser || 'zhparser'});
+                    ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
                 `;
-                    await this.connector.exec(createChineseConfigSql);
-                }
+                await this.connector.exec(createChineseConfigSql, txn);
+            }
+        });
+    }
+    async createManagedSchema(option) {
+        const schema = this.getSchema();
+        const entities = Object.keys(schema);
+        console.log('Initializing PostgreSQL schema create phase...');
+        for (let idx = 0; idx < entities.length; idx++) {
+            const entity = entities[idx];
+            if (this.shouldLogInitializeProgress(idx + 1, entities.length, 10)) {
+                console.log(`Initializing PostgreSQL tables (${idx + 1}/${entities.length}): ${entity}`);
             }
-            for (const entity in schema) {
-                const sqls = this.translator.translateCreateEntity(entity, option);
+            const sqls = this.translator.translateCreateEntity(entity, option);
+            await this.runInitializeTransaction(async (txn) => {
                 for (const sql of sqls) {
                     await this.connector.exec(sql, txn);
                 }
+            });
+        }
+    }
+    async applyForeignKeysFromPlan(plan) {
+        const foreignKeySqls = [
+            ...plan.forwardSql.filter((stmt) => /foreign key/i.test(stmt)),
+            ...plan.manualSql.filter((stmt) => /add constraint .*foreign key/i.test(stmt)),
+        ];
+        console.log('Initializing PostgreSQL foreign key phase...');
+        // FK 逐条独立执行，让每条 ALTER TABLE 自己提交。
+        // 这样不会再把所有引用关系的锁堆到同一个事务里。
+        for (let idx = 0; idx < foreignKeySqls.length; idx++) {
+            if (this.shouldLogInitializeProgress(idx + 1, foreignKeySqls.length, 20)) {
+                console.log(`Initializing PostgreSQL foreign keys (${idx + 1}/${foreignKeySqls.length})`);
             }
-            await this.connector.commitTransaction(txn);
+            await this.connector.exec(foreignKeySqls[idx]);
         }
-        catch (error) {
-            await this.connector.rollbackTransaction(txn);
-            throw error;
+    }
+    async applyDeclaredForeignKeys() {
+        const plan = this.connector.diffSchema({}, this.translator.schema, this.translator, {
+            compareForeignKeys: true,
+        });
+        await this.applyForeignKeysFromPlan(plan);
+    }
+    async applyMissingForeignKeys() {
+        const inspection = await this.connector.inspectSchema(this.translator);
+        const plan = this.connector.diffSchema(inspection.schema, this.translator.schema, this.translator, {
+            compareForeignKeys: true,
+            currentTableStats: inspection.tableStats,
+        });
+        await this.applyForeignKeysFromPlan(plan);
+    }
+    async initialize(option) {
+        const schema = this.getSchema();
+        const entities = Object.keys(schema);
+        console.log('Initializing PostgreSQL prepare phase...');
+        // PostgreSQL 初始化拆成“事务外准备”和“事务内建表”两段：
+        // 扩展/解析器这类对象不能简单塞进同一个 DDL 事务，但表结构本身又希望保持原子性。
+        // ===== 第一阶段：事务外创建扩展 =====
+        let hasGeoType = false;
+        let hasChineseTsConfig = false;
+        let chineseParser = null;
+        // 扫描 schema
+        for (const entity of entities) {
+            const { attributes, indexes } = schema[entity];
+            for (const attr in attributes) {
+                if (attributes[attr].type === 'geometry') {
+                    hasGeoType = true;
+                }
+            }
+            for (const index of indexes || []) {
+                if (index.config?.tsConfig === 'chinese' || index.config?.tsConfig?.includes('chinese')) {
+                    hasChineseTsConfig = true;
+                }
+                if (index.config?.chineseParser) {
+                    (0, assert_1.default)(!chineseParser || chineseParser === index.config.chineseParser, '当前定义了多个中文分词器，请保持一致');
+                    chineseParser = index.config.chineseParser;
+                }
+            }
+        }
+        // 在事务外创建扩展
+        if (hasGeoType) {
+            console.log('Initializing PostGIS extension for geometry support...');
+            await this.connector.exec('CREATE EXTENSION IF NOT EXISTS postgis;');
+        }
+        if (hasChineseTsConfig) {
+            console.log('Initializing Chinese parser extension...');
+            await this.connector.exec(`CREATE EXTENSION IF NOT EXISTS ${chineseParser || 'zhparser'};`);
+        }
+        // ===== 第二阶段：按初始化单元分批执行事务 =====
+        // 文本检索配置、每个实体的建表 DDL、以及每条 FK 的 ALTER TABLE
+        // 都拆开提交，避免大 schema 初始化时单事务积累过多 relation locks。
+        await this.ensureChineseTextSearchConfiguration(hasChineseTsConfig, chineseParser);
+        await this.createManagedSchema(option);
+        if (this.isFullManagedReset(option)) {
+            await this.applyDeclaredForeignKeys();
+        }
+        else {
+            await this.applyMissingForeignKeys();
         }
     }
     // 从数据库中读取当前schema
     readSchema() {
-        return this.translator.readSchema((sql) => this.connector.exec(sql));
+        return this.connector.readSchema(this.translator);
     }
     /**
      * 根据载入的dataSchema，和数据库中原来的schema，决定如何来upgrade
      * 制订出来的plan分为两阶段：增加阶段和削减阶段，在两个阶段之间，由用户来修正数据
      */
-    async makeUpgradePlan() {
-        const originSchema = await this.readSchema();
-        const plan = this.diffSchema(originSchema, this.translator.schema);
+    async makeUpgradePlan(options) {
+        const inspection = await this.connector.inspectSchema(this.translator);
+        const plan = this.diffSchema(inspection.schema, this.translator.schema, {
+            ...options,
+            currentTableStats: options?.currentTableStats || inspection.tableStats,
+        });
         return plan;
     }
     /**
@@ -411,117 +553,8 @@ class PostgreSQLStore extends CascadeStore_1.CascadeStore {
      * @param schemaOld
      * @param schemaNew
      */
-    diffSchema(schemaOld, schemaNew) {
-        const plan = {
-            newTables: {},
-            newIndexes: {},
-            updatedIndexes: {},
-            updatedTables: {},
-        };
-        for (const table in schemaNew) {
-            // PostgreSQL 表名区分大小写（使用双引号时）
-            if (schemaOld[table]) {
-                const { attributes, indexes } = schemaOld[table];
-                const { attributes: attributesNew, indexes: indexesNew } = schemaNew[table];
-                const assignToUpdateTables = (attr, isNew) => {
-                    const skipAttrs = ['$$seq$$', '$$createAt$$', '$$updateAt$$', '$$deleteAt$$', 'id'];
-                    if (skipAttrs.includes(attr)) {
-                        return;
-                    }
-                    if (!plan.updatedTables[table]) {
-                        plan.updatedTables[table] = {
-                            attributes: {
-                                [attr]: {
-                                    ...attributesNew[attr],
-                                    isNew,
-                                }
-                            }
-                        };
-                    }
-                    else {
-                        plan.updatedTables[table].attributes[attr] = {
-                            ...attributesNew[attr],
-                            isNew,
-                        };
-                    }
-                };
-                for (const attr in attributesNew) {
-                    if (attributes[attr]) {
-                        // 比较两次创建的属性定义是否一致
-                        const sql1 = this.translator.translateAttributeDef(attr, attributesNew[attr]);
-                        const sql2 = this.translator.translateAttributeDef(attr, attributes[attr]);
-                        if (!this.translator.compareSql(sql1, sql2)) {
-                            assignToUpdateTables(attr, false);
-                        }
-                    }
-                    else {
-                        assignToUpdateTables(attr, true);
-                    }
-                }
-                if (indexesNew) {
-                    const assignToIndexes = (index, isNew) => {
-                        if (isNew) {
-                            if (plan.newIndexes[table]) {
-                                plan.newIndexes[table].push(index);
-                            }
-                            else {
-                                plan.newIndexes[table] = [index];
-                            }
-                        }
-                        else {
-                            if (plan.updatedIndexes[table]) {
-                                plan.updatedIndexes[table].push(index);
-                            }
-                            else {
-                                plan.updatedIndexes[table] = [index];
-                            }
-                        }
-                    };
-                    const compareConfig = (config1, config2) => {
-                        const unique1 = config1?.unique || false;
-                        const unique2 = config2?.unique || false;
-                        if (unique1 !== unique2) {
-                            return false;
-                        }
-                        const type1 = config1?.type || 'btree';
-                        const type2 = config2?.type || 'btree';
-                        // tsConfig 比较
-                        const tsConfig1 = config1?.tsConfig;
-                        const tsConfig2 = config2?.tsConfig;
-                        if (JSON.stringify(tsConfig1) !== JSON.stringify(tsConfig2)) {
-                            return false;
-                        }
-                        return type1 === type2;
-                    };
-                    for (const index of indexesNew) {
-                        const { name, config, attributes: indexAttrs } = index;
-                        const origin = indexes?.find(ele => ele.name === name);
-                        if (origin) {
-                            if (JSON.stringify(indexAttrs) !== JSON.stringify(origin.attributes)) {
-                                assignToIndexes(index, false);
-                            }
-                            else {
-                                if (!compareConfig(config, origin.config)) {
-                                    assignToIndexes(index, false);
-                                }
-                            }
-                        }
-                        else {
-                            assignToIndexes(index, true);
-                        }
-                    }
-                }
-            }
-            else {
-                plan.newTables[table] = {
-                    attributes: schemaNew[table].attributes,
-                };
-                if (schemaNew[table].indexes) {
-                    plan.newIndexes[table] = schemaNew[table].indexes;
-                }
-            }
-        }
-        return plan;
+    diffSchema(schemaOld, schemaNew, options) {
+        return this.connector.diffSchema(schemaOld, schemaNew, this.translator, options);
     }
 }
 exports.PostgreSQLStore = PostgreSQLStore;

package/lib/PostgreSQL/translator.d.ts

@@ -6,9 +6,22 @@ import { CreateEntityOption } from '../types/Translator';
 export interface PostgreSQLSelectOption extends SqlSelectOption {
 }
 export interface PostgreSQLOperateOption extends SqlOperateOption {
+    /**
+     * PostgreSQL RETURNING 子句的投影
+     * 仅在 update/remove 时有效
+     * 返回受影响的行
+     */
+    returning?: Record<string, any>;
 }
 export declare class PostgreSQLTranslator<ED extends EntityDict & BaseEntityDict> extends SqlTranslator<ED> {
-    private getEnumTypeName;
+    readonly maxIndexNameLength = 63;
+    private physicalIndexNameCache?;
+    private makeIndexNameCacheKey;
+    private getIndexSuffixes;
+    private ensurePhysicalIndexNameCache;
+    getEnumTypeName(entity: string, attr: string): string;
+    getPhysicalIndexName(entityName: string, tableName: string, logicalName: string, suffix?: string): string;
+    getLegacyPhysicalIndexNames(entityName: string, tableName: string, logicalName: string, suffix?: string): string[];
     /**
      * 将 MySQL 风格的 JSON 路径转换为 PostgreSQL 路径数组格式
      * 例如: ".foo.bar[0].baz" -> '{foo,bar,0,baz}'
@@ -63,16 +76,22 @@ export declare class PostgreSQLTranslator<ED extends EntityDict & BaseEntityDict
     protected translateExpression<T extends keyof ED>(entity: T, alias: string, expression: RefOrExpression<keyof ED[T]["OpSchema"]>, refDict: Record<string, [string, keyof ED]>): string;
     protected populateSelectStmt<T extends keyof ED>(projectionText: string, fromText: string, aliasDict: Record<string, string>, filterText: string, sorterText?: string, groupByText?: string, indexFrom?: number, count?: number, option?: PostgreSQLSelectOption): string;
     translateUpdate<T extends keyof ED, OP extends SqlOperateOption>(entity: T, operation: ED[T]['Update'], option?: OP): string;
-    translateRemove<T extends keyof ED, OP extends SqlOperateOption>(entity: T, operation: ED[T]['Remove'], option?: OP): string;
     /**
-     * PostgreSQL专用的结构化JOIN分析
-     * 返回结构化的JOIN信息，而不是拼接好的FROM字符串
+     * 将 projection 转换为 RETURNING 子句的列列表
+     * @param entity 实体名
+     * @param alias 表别名
+     * @param projection 投影定义
      */
-    private analyzeJoinStructured;
+    private buildReturningClause;
     /**
-     * 构建JOIN条件（用于UPDATE/DELETE的WHERE子句）
+     * 验证操作参数的合法性
      */
-    private buildJoinConditions;
+    private validateOperationParams;
+    /**
+     * 添加RETURNING子句
+     */
+    private appendReturningClause;
+    translateRemove<T extends keyof ED, OP extends SqlOperateOption>(entity: T, operation: ED[T]['Remove'], option?: OP): string;
     /**
      * 生成 PostgreSQL UPSERT 语句
      * INSERT ... ON CONFLICT (key) DO UPDATE SET ...
@@ -84,7 +103,7 @@ export declare class PostgreSQLTranslator<ED extends EntityDict & BaseEntityDict
      * 将 PostgreSQL 返回的 Type 回译成 oak 的类型，是 populateDataTypeDef 的反函数
      * @param type PostgreSQL 类型字符串
      */
-    private reTranslateToAttribute;
+    reTranslateToAttribute(type: string): Attribute;
     /**
      * 从 PostgreSQL 数据库读取当前的 schema 结构
      */
@@ -95,6 +114,7 @@ export declare class PostgreSQLTranslator<ED extends EntityDict & BaseEntityDict
      * @param attrDef 属性定义
      */
     translateAttributeDef(attr: string, attrDef: Attribute): string;
+    translateColumnDefinition(entity: string, attr: string, attrDef: Attribute): string;
     /**
      * 比较两个 SQL 语句是否等价（用于 schema diff）
      * 忽略空格、大小写等格式差异