@itwin/core-backend 5.14.0-dev.1 → 5.14.0-dev.10

package/lib/esm/IModelDb.js

@@ -317,7 +317,9 @@ export class IModelDb extends IModel {
                         db[_nativeDb].abandonChanges();
                         db.close();
                     }
-                    catch { }
+                    catch {
+                        return;
+                    }
                 });
             });
         }
@@ -383,12 +385,20 @@ export class IModelDb extends IModel {
         this._codeService = undefined;
         this[_nativeDb].closeFile();
     }
+    /**
+     * Save any unsaved schema changes in this iModel.
+     * @internal
+    */
     saveSchemaChanges(args) {
         if (!this[_nativeDb].hasUnsavedChanges())
             return;
         const saveArgs = typeof args === "string" ? { description: args } : args;
         saveArgs === undefined ? this[_nativeDb].saveChanges() : this[_nativeDb].saveChanges(JSON.stringify(saveArgs));
     }
+    /**
+     * Abandon any unsaved schema changes in this iModel.
+     * @internal
+     */
     abandonSchemaChanges() {
         if (!this[_nativeDb].hasUnsavedChanges())
             return;
@@ -431,24 +441,30 @@ export class IModelDb extends IModel {
     }
     /**
      * Performs integrity checks on this iModel.
-     * Types of integrity checks that can be performed are:
      *
-     * Default Check:
-     * - Quick Check: Runs all integrity checks below and returns whether each check passed or failed, without detailed results.
+     * The quick check runs the ten checks below other than Missing Child Rows. It reports pass/fail for each check
+     * based on the first problem found, without returning problem details. The specific checks return all problem rows.
+     * Selecting both quickCheck and specific checks repeats the selected work in both modes.
+     *
+     * The checks are:
+     * - Data Columns Check: Checks for missing nonvirtual physical columns in mapped data tables. It does not compare column types.
+     * - EC Profile Check: Checks expected EC profile tables, indexes, and iModel triggers for missing or mismatching SQL definitions. It does not check be_* tables.
+     * - Navigation Class Ids Check: Checks that each non-null persisted RelECClassId is the declared relationship class or one of its derived classes.
+     * - Navigation Ids Check: Checks that a navigation property's non-null .Id (the referenced instance's ECInstanceId) resolves to a row in the first relationship constraint class in the navigation direction, including derived classes.
+     * - Linktable Foreign Key Class Ids Check: Checks that SourceECClassId and TargetECClassId have matching meta.ECClassDef entries. This checks class existence only, not endpoint-class validity.
+     * - Linktable Foreign Key Ids Check: Checks SourceECInstanceId and TargetECInstanceId for null or an unresolved row in the first endpoint constraint class, including derived classes.
+     * - Class Ids Check: Checks persisted ECClassId values for a corresponding class definition. This checks class existence, not whether the class belongs in that table.
+     * - Data Schema Check: Checks for missing mapped data tables and indexes. Results report object names and types, not DDL differences.
+     * - Schema Load Check: Checks whether the schema manager can load each schema recorded in the database. A problem reports the schema name without a reason.
+     * - Missing Child Rows Check: Checks whether each existing bis_Element row has all required mapped child-table rows.
+     * - Diverged Property Maps Check: Checks whether an inherited property maps to different columns for a base and derived class under the same physical table root.
      *
-     * Specific Checks:
-     * - Data Columns Check: Checks if all the required columns exist in data tables. Issues are returned as a list of those tables/columns.
-     * - EC Profile Check: Checks if the profile table, indexes, and triggers are present. Does not check be_* tables. Issues are returned as a list of tables/indexes/triggers which were not found or have different DDL.
-     * - Navigation Class Ids Check: Checks if RelClassId of a Navigation property is a valid ECClassId. It does not check the value to match the relationship class.
-     * - Navigation Ids Check: Checks if Id of a Navigation property matches a valid row primary class.
-     * - Linktable Foreign Key Class Ids Check: Checks if SourceECClassId or TargetECClassId of a link table matches a valid ECClassId.
-     * - Linktable Foreign Key Ids Check: Checks if SourceECInstanceId or TargetECInstanceId of a link table matches a valid row in primary class.
-     * - Class Ids Check: Checks persisted ECClassId in all data tables and makes sure they are valid.
-     * - Data Schema Check: Checks if all the required data tables and indexes exist for mapped classes. Issues are returned as a list of tables/columns which were not found or have different DDL.
-     * - Schema Load Check: Checks if all schemas can be loaded into memory.
-     * - Missing Child Rows Check: Checks if all child rows have a corresponding parent row.
+     * If no options are provided, or if quickCheck is false and no specific check is enabled, a quick check is performed by default.
+     * The checks are read-only and use the current primary connection. They have no callbacks, and the native operation
+     * blocks the backend while each check runs.
      *
-     * @param options Options specifying which integrity checks to perform. If no options are provided or all options are false, a quick check will be performed by default.
+     * @see [ECSQL integrity checks]($docs/learning/ECSqlReference/Pragmas.md#pragma-integrity_check-experimental)
+     * @param options Options specifying which integrity checks to perform.
      * @returns An array of integrity check results.
      * @throws [[IModelError]] if the iModel is not open.
      * @beta
@@ -935,7 +951,7 @@ export class IModelDb extends IModel {
     async dropSchemas(schemaNames) {
         if (schemaNames.length === 0)
             return;
-        if (this[_nativeDb].schemaSyncEnabled())
+        if (SchemaSync.isEnabled(this))
             throw new IModelError(DbResult.BE_SQLITE_ERROR, "Cannot drop schemas when schema sync is enabled");
         if (this[_nativeDb].hasUnsavedChanges())
             throw new IModelError(ChangeSetStatus.HasUncommittedChanges, "Cannot drop schemas with unsaved changes");
@@ -1021,26 +1037,34 @@ export class IModelDb extends IModel {
             this.cleanupSnapshot(context.resources);
         }
     }
-    /** Shared implementation for importing schemas from file or string. */
-    async importSchemasInternal(schemas, options, nativeImportOp) {
-        // BriefcaseDb-specific validation checks
-        if (this.isBriefcaseDb()) {
-            if (this.txns.rebaser.isRebasing) {
-                throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas while rebasing");
-            }
-            if (this.txns.isIndirectChanges) {
-                throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas while in an indirect change scope");
-            }
-            // Additional checks when semantic rebase is enabled
-            if (IModelHost.useSemanticRebase) {
-                if (this[_nativeDb].hasUnsavedChanges()) {
-                    throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas with unsaved changes when useSemanticRebase flag is on");
-                }
-                if (this[_nativeDb].schemaSyncEnabled()) {
-                    throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas when schema sync is enabled and also useSemanticRebase flag is on");
-                }
+    /** Refuse a schema import this briefcase is in no state to run. Shared by [[importSchemas]] and
+     * [[BriefcaseDb.upgradeSchemas]], which reach the native importer by different routes.
+     * @internal
+     */
+    assertCanImportSchemas() {
+        if (!this.isBriefcaseDb())
+            return;
+        if (this.txns.rebaser.isRebasing) {
+            throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas while rebasing");
+        }
+        if (this.txns.isIndirectChanges) {
+            throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas while in an indirect change scope");
+        }
+        // Additional checks when semantic rebase is enabled
+        if (IModelHost.useSemanticRebase) {
+            if (this[_nativeDb].hasUnsavedChanges()) {
+                throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas with unsaved changes when useSemanticRebase flag is on");
+            }
+            if (SchemaSync.isEnabled(this)) {
+                throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas when schema sync is enabled and also useSemanticRebase flag is on");
             }
         }
+    }
+    /** Shared implementation for importing schemas from file or string.
+     * @internal
+     */
+    async importSchemasInternal(schemas, options, nativeImportOp) {
+        this.assertCanImportSchemas();
         if (options?.channelUpgrade) {
             const channelUpgrade = options.channelUpgrade;
             try {
@@ -1058,30 +1082,52 @@ export class IModelDb extends IModel {
         if (options?.schemaImportCallbacks?.preSchemaImportCallback)
             preSchemaImportCallbackResult = await this.preSchemaImportCallback(options.schemaImportCallbacks, { iModel: this, data: options.data, schemaData: schemas });
         const maybeCustomNativeContext = options?.ecSchemaXmlContext?.nativeContext;
-        if (this[_nativeDb].schemaSyncEnabled()) {
-            await SchemaSync.withLockedAccess(this, { openMode: OpenMode.Readonly, operationName: "schema sync" }, async (syncAccess) => {
-                const schemaSyncDbUri = syncAccess.getUri();
-                this.saveSchemaChanges();
-                try {
-                    nativeImportOp(schemas, { schemaLockHeld: false, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
-                }
-                catch (outerErr) {
-                    if (DbResult.BE_SQLITE_ERROR_DataTransformRequired === outerErr.errorNumber) {
-                        this.abandonSchemaChanges();
-                        if (this[_nativeDb].getITwinId() !== Guid.empty)
-                            await this.acquireSchemaLock();
-                        try {
-                            nativeImportOp(schemas, { schemaLockHeld: true, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
-                        }
-                        catch (innerErr) {
-                            throw new IModelError(innerErr.errorNumber, innerErr.message);
-                        }
+        if (SchemaSync.isEnabled(this)) {
+            // The shared lock lets concurrent updates through while blocking anyone taking the exclusive lock for an upgrade.
+            if (this[_nativeDb].getITwinId() !== Guid.empty)
+                await this.locks.acquireLocks({ shared: IModel.repositoryModelId });
+            // The native import adopts rows from the attached SchemaSyncDb. Attach and detach commit
+            // implicitly, so abandoning changes cannot undo the adoption. A later failure must roll the
+            // briefcase back before those ec_ rows can be pushed.
+            let txnBeforeAdopt;
+            // Set once the caller's own work is committed. Getting a token or the container write lock happens
+            // before that, and abandonSchemaChanges discards every unsaved change rather than only this import's,
+            // so abandoning on a failure from that window would throw away work the import never touched.
+            let callerChangesSaved = false;
+            try {
+                await SchemaSync.withLockedAccess(this, { openMode: OpenMode.Readonly, operationName: "schema sync" }, async (syncAccess) => {
+                    const schemaSyncDbUri = syncAccess.getUri();
+                    this.saveSchemaChanges();
+                    callerChangesSaved = true;
+                    // After saveSchemaChanges, so rolling back cannot reach the caller's own work.
+                    if (this.isBriefcaseDb())
+                        txnBeforeAdopt = this.txns.getCurrentTxnId();
+                    try {
+                        nativeImportOp(schemas, { schemaLockHeld: false, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
                     }
-                    else {
-                        throw new IModelError(outerErr.errorNumber, outerErr.message);
+                    catch (err) {
+                        if (SchemaSync.requiresUpgrade(err))
+                            throw new IModelError(err.errorNumber, `${err.message} - this schema change needs the upgrade path. Use BriefcaseDb.upgradeSchemas, which takes the exclusive schema lock and pushes the result.`);
+                        throw new IModelError(err.errorNumber, err.message);
                     }
+                });
+            }
+            catch (err) {
+                if (callerChangesSaved)
+                    this.abandonSchemaChanges();
+                if (this.isBriefcaseDb() && undefined !== txnBeforeAdopt && this.txns.getCurrentTxnId() !== txnBeforeAdopt) {
+                    // Saving the adopt's txn started a new undo session, because schema changes are kept out of the
+                    // user's undo stack, so this reverses across that boundary. The changes themselves reverse like
+                    // any other - a rebase does it to every local txn on every pull. It does not reverse DDL: a table
+                    // or column the adopt created stays behind with no ec_ row describing it, which is the state a
+                    // briefcase already tolerates, and the next successful import finds the table up to date and
+                    // carries on. Cancel rather than reverse, so the rows cannot come back through undo either.
+                    const status = this[_nativeDb].cancelTo(txnBeforeAdopt, true);
+                    if (IModelStatus.Success !== status)
+                        Logger.logError(loggerCategory, `Failed to roll back the adopted schema rows after a failed import: ${IModelStatus[status] ?? status}`);
                 }
-            });
+                throw err;
+            }
         }
         else {
             const nativeImportOptions = {
@@ -2846,7 +2892,9 @@ function processSchemaWriteStatus(status) {
                 try {
                     props.push(imodel.elements.getElementProps(id));
                 }
-                catch { }
+                catch {
+                    return;
+                }
             });
             return props;
         }
@@ -2869,7 +2917,9 @@ function processSchemaWriteStatus(status) {
                             break;
                     }
                 }
-                catch { }
+                catch {
+                    continue;
+                }
             }
             return finished;
         }
@@ -3079,9 +3129,6 @@ export class BriefcaseDb extends IModelDb {
     get isBriefcase() { return true; }
     /* the BriefcaseId of the briefcase opened with this BriefcaseDb */
     briefcaseId;
-    _skipSyncSchemasOnPullAndPush;
-    /** @internal */
-    get skipSyncSchemasOnPullAndPush() { return this._skipSyncSchemasOnPullAndPush ?? false; }
     /**
      * Event raised just before a BriefcaseDb is opened. Supplies the arguments that will be used to open the BriefcaseDb.
      * Throw an exception to stop the open.
@@ -3164,6 +3211,8 @@ export class BriefcaseDb extends IModelDb {
     }
     constructor(args) {
         super({ ...args, changeset: args.nativeDb.getCurrentChangeset() });
+        // Native invokes this private callback dynamically through the object registered by IModelDb.
+        void this.onChangesetConflict;
         this._openMode = args.openMode;
         this.briefcaseId = args.briefcaseId;
         this.makeLockControl();
@@ -3176,26 +3225,33 @@ export class BriefcaseDb extends IModelDb {
             wasChanges = nativeDb.hasPendingTxns();
             nativeDb.closeFile();
         };
-        const isSchemaSyncEnabled = await withBriefcaseDb(briefcase, async (db) => {
-            await SchemaSync.pull(db);
-            return db[_nativeDb].schemaSyncEnabled();
-        });
-        if (isSchemaSyncEnabled) {
+        const push = async () => {
+            if (wasChanges)
+                await withBriefcaseDb(briefcase, async (db) => db.pushChanges({ ...briefcase, description, retainLocks: true }));
+        };
+        // Asked of the closed file, so an iModel without schema sync never gets opened for this.
+        if (SchemaSync.isEnabled(briefcase)) {
+            await withBriefcaseDb(briefcase, async (db) => SchemaSync.updateDbSchema(db));
             await SchemaSync.withLockedAccess(briefcase, { openMode: OpenMode.Readonly, operationName: "schema sync" }, async (syncAccess) => {
                 const schemaSyncDbUri = syncAccess.getUri();
                 executeUpgrade();
+                // Overwriting advances the SchemaSync data version, so a no-op upgrade must not call it.
+                if (!wasChanges)
+                    return;
                 await withBriefcaseDb(briefcase, async (db) => {
-                    db[_nativeDb].schemaSyncPush(schemaSyncDbUri);
+                    db[_nativeDb].schemaSyncOverwrite(schemaSyncDbUri);
                     db[_nativeDb].saveChanges();
                 });
-                syncAccess.synchronizeWithCloud();
+                // Publish the sync db before the changeset while retaining both locks.
+                syncAccess.closeDb();
+                await syncAccess.container.uploadChanges();
+                await push();
             });
         }
         else {
             executeUpgrade();
+            await push();
         }
-        if (wasChanges)
-            await withBriefcaseDb(briefcase, async (db) => db.pushChanges({ ...briefcase, description, retainLocks: true }));
     }
     /** Upgrades the schemas in the iModel based on the current version of the software. Follows a sequence of operations -
      * * Acquires a schema lock to prevent other users from making any other changes while upgrade is happening
@@ -3215,6 +3271,22 @@ export class BriefcaseDb extends IModelDb {
         // - push changes
         // - release schema lock
         // good thing computers are fast. Fortunately upgrading should be rare (and the push time will dominate anyway.) Don't try to optimize any of this away.
+        // schemaSyncOverwrite can discard unpushed imports, so hold the exclusive lock across both upgrades.
+        if (SchemaSync.isEnabled(briefcase)) {
+            try {
+                await withBriefcaseDb(briefcase, async (db) => {
+                    if (!db.locks.isServerBased)
+                        throw new IModelError(DbResult.BE_SQLITE_ERROR, "Cannot upgrade schemas with SchemaSync without server-based locking");
+                    await db.acquireSchemaLock();
+                });
+                await this.doUpgrade(briefcase, { profile: ProfileOptions.Upgrade, schemaLockHeld: true }, "Upgraded profile");
+                await this.doUpgrade(briefcase, { domain: DomainOptions.Upgrade, schemaLockHeld: true }, "Upgraded domain schemas");
+            }
+            finally {
+                await withBriefcaseDb(briefcase, async (db) => db.locks[_releaseAllLocks]());
+            }
+            return;
+        }
         try {
             await this.doUpgrade(briefcase, { profile: ProfileOptions.Upgrade }, "Upgraded profile");
         }
@@ -3515,8 +3587,7 @@ export class BriefcaseDb extends IModelDb {
     async pullChanges(arg) {
         await this.executeWritable(async () => {
             await BriefcaseManager.pullAndApplyChangesets(this, arg ?? {});
-            if (!this.skipSyncSchemasOnPullAndPush)
-                await SchemaSync.pull(this);
+            SchemaSync.updateDbSchema(this);
             this.initializeIModelDb("pullMerge");
         });
         // If this pull enabled or disabled SchemaSync for this briefcase, its reservations must now be re-initialized
@@ -3601,24 +3672,10 @@ export class BriefcaseDb extends IModelDb {
         if (nativeDb.hasPendingTxns()) {
             throw new IModelError(ChangeSetStatus.HasLocalChanges, "Cannot revert with pending txns");
         }
-        const skipSchemaSyncPull = async (func) => {
-            if (nativeDb.schemaSyncEnabled()) {
-                this._skipSyncSchemasOnPullAndPush = true;
-                try {
-                    return await func();
-                }
-                finally {
-                    this._skipSyncSchemasOnPullAndPush = undefined;
-                }
-            }
-            else {
-                return func();
-            }
-        };
         this.clearCaches();
-        await skipSchemaSyncPull(async () => this.pullChanges({ ...arg, toIndex: undefined }));
+        await this.pullChanges({ ...arg, toIndex: undefined });
         await this.acquireSchemaLock();
-        if (nativeDb.schemaSyncEnabled()) {
+        if (SchemaSync.isEnabled(this)) {
             arg.skipSchemaChanges = true;
         }
         // The native side enables file-based txns during revert. Restore the original setting afterward.
@@ -3639,7 +3696,7 @@ export class BriefcaseDb extends IModelDb {
                 pushRetryDelay: arg.pushRetryDelay,
                 retainLocks: arg.retainLocks,
             };
-            await skipSchemaSyncPull(async () => this.pushChanges(pushArgs));
+            await this.pushChanges(pushArgs);
             this.clearCaches();
         }
         catch (err) {
@@ -3716,6 +3773,56 @@ export class BriefcaseDb extends IModelDb {
         this.txns._onChangesPushed(this.changeset);
         BriefcaseManager.deleteRebaseFolders(this);
     }
+    /** Import schemas while allowing changes that move or delete data.
+     *
+     * Takes the exclusive schema lock, requires the briefcase to be at the timeline tip, imports, updates the sync db, and pushes the result.
+     * @note The briefcase must have no local changes.
+     * @see [[BriefcaseDb.upgradeSchemas]] (static) for upgrading the software's profile and domain schemas.
+     * @alpha
+     */
+    async upgradeSchemas(schemaFileNames, arg) {
+        return this.upgradeSchemasInternal(schemaFileNames, arg, (schemas, importOptions) => this[_nativeDb].importSchemas(schemas, importOptions));
+    }
+    /** The [[importSchemaStrings]] counterpart of [[upgradeSchemas]].
+     * @alpha
+     */
+    async upgradeSchemaStrings(serializedXmlSchemas, arg) {
+        return this.upgradeSchemasInternal(serializedXmlSchemas, arg, (schemas, importOptions) => this[_nativeDb].importXmlSchemas(schemas, importOptions));
+    }
+    async upgradeSchemasInternal(schemas, arg, nativeImportOp) {
+        if (schemas.length === 0)
+            return;
+        this.assertCanImportSchemas();
+        if (this[_nativeDb].hasUnsavedChanges() || this.txns.hasLocalChanges)
+            throw new IModelError(ChangeSetStatus.HasLocalChanges, "Cannot upgrade schemas while there are local changes");
+        if (SchemaSync.isEnabled(this) && !this.locks.isServerBased)
+            throw new IModelError(DbResult.BE_SQLITE_ERROR, "Cannot upgrade schemas with SchemaSync without server-based locking");
+        await this.acquireSchemaLock();
+        await this.pullChanges({ accessToken: arg.accessToken });
+        if (!SchemaSync.isEnabled(this)) {
+            await this.importSchemasInternal(schemas, { ecSchemaXmlContext: arg.ecSchemaXmlContext }, nativeImportOp);
+            await this.pushChanges(arg);
+            return;
+        }
+        await SchemaSync.withLockedAccess(this, { openMode: OpenMode.Readonly, operationName: "schema upgrade" }, async (syncAccess) => {
+            this.saveSchemaChanges();
+            try {
+                nativeImportOp(schemas, {
+                    schemaLockHeld: true,
+                    ecSchemaXmlContext: arg.ecSchemaXmlContext?.nativeContext,
+                    schemaSyncDbUri: syncAccess.getUri(),
+                });
+            }
+            catch (err) {
+                this.abandonSchemaChanges();
+                throw new IModelError(err.errorNumber, err.message);
+            }
+            this.clearCaches();
+            syncAccess.closeDb();
+            await syncAccess.container.uploadChanges();
+            await this.pushChanges(arg);
+        });
+    }
     close(options) {
         if (this.isBriefcase && this.isOpen && !this.isReadonly && this.txns.rebaser.inProgress()) {
             this[_nativeDb].abandonChanges();