@itwin/core-backend 5.13.0-dev.8 → 5.13.0

package/lib/esm/IModelDb.js

@@ -8,7 +8,7 @@
 import * as fs from "fs";
 import { join } from "path";
 import * as touch from "touch";
-import { assert, BeEvent, BentleyStatus, ChangeSetStatus, DbChangeStage, DbConflictCause, DbConflictResolution, DbResult, Guid, Id64, IModelStatus, JsonUtils, Logger, LogLevel, LRUMap, OpenMode } from "@itwin/core-bentley";
+import { assert, BeEvent, BentleyStatus, ChangeSetStatus, DbChangeStage, DbConflictCause, DbConflictResolution, DbOpcode, DbResult, Guid, Id64, IModelStatus, JsonUtils, Logger, LogLevel, LRUMap, OpenMode } from "@itwin/core-bentley";
 import { Base64EncodedString, BriefcaseIdValue, Code, DomainOptions, ECJsNames, ECSqlReader, EditTxnError, EntityMetaData, FontMap, IModel, IModelError, IModelNotFoundResponse, ProfileOptions, QueryBinder, QueryRowFormat, resolveNavPropId, SchemaState, ViewStoreError, ViewStoreRpc } from "@itwin/core-common";
 import { Range2d, Range3d } from "@itwin/core-geometry";
 import { BackendLoggerCategory } from "./BackendLoggerCategory";
@@ -45,7 +45,9 @@ import { constructWorkspace, throwWorkspaceDbLoadErrors } from "./internal/works
 import { SettingsImpl } from "./internal/workspace/SettingsImpl";
 import { IModelNative } from "./internal/NativePlatform";
 import { createNoOpLockControl } from "./internal/NoLocks";
+import { createNoOpReservations } from "./internal/NoReservations";
 import { createIModelDbFonts } from "./internal/IModelDbFontsImpl";
+import { createSchemaSyncReservations } from "./internal/SchemaSyncReservations";
 import { _activeTxn, _cache, _close, _hubAccess, _implicitTxn, _instanceKeyCache, _nativeDb, _releaseAllLocks, _resetIModelDb } from "./internal/Symbols";
 import { ECVersion, SchemaContext, SchemaJsonLocater, SchemaManifest, SchemaViewManager } from "@itwin/ecschema-metadata";
 import { SchemaMap } from "./Schema";
@@ -175,6 +177,8 @@ export class IModelDb extends IModel {
     /** @internal */
     _locks = createNoOpLockControl();
     /** @internal */
+    _reservations = createNoOpReservations();
+    /** @internal */
     _codeService;
     /**
      * The always-available implicit transaction for this iModel.
@@ -203,6 +207,16 @@ export class IModelDb extends IModel {
     get codeService() { return this._codeService; }
     /** The [[LockControl]] that orchestrates [concurrent editing]($docs/learning/backend/ConcurrencyControl.md) of this iModel. */
     get locks() { return this._locks; } // eslint-disable-line @typescript-eslint/no-non-null-assertion
+    /** @beta The [[SynchronousChannel.Reservations]] that orchestrates [concurrent editing]($docs/learning/backend/ConcurrencyControl.md) of this iModel. */
+    get reservations() { return this._reservations; } // eslint-disable-line @typescript-eslint/no-non-null-assertion
+    /** @internal */
+    async initializeSharedElementReservations() {
+        this._reservations?.[_close]();
+        if (SchemaSync.isEnabled(this))
+            this._reservations = await createSchemaSyncReservations(this);
+        else
+            this._reservations = createNoOpReservations();
+    }
     /** Provides methods for interacting with [font-related information]($docs/learning/backend/Fonts.md) stored in this iModel.
      * @beta
      */
@@ -303,7 +317,9 @@ export class IModelDb extends IModel {
                         db[_nativeDb].abandonChanges();
                         db.close();
                     }
-                    catch { }
+                    catch {
+                        return;
+                    }
                 });
             });
         }
@@ -363,16 +379,26 @@ export class IModelDb extends IModel {
         this.views[_close]();
         this.locks[_close]();
         this._locks = undefined;
+        this.reservations[_close]();
+        this._reservations = undefined;
         this._codeService?.close();
         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;
@@ -919,7 +945,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");
@@ -1005,26 +1031,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 {
@@ -1042,30 +1076,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 = {
@@ -2174,7 +2230,7 @@ function processSchemaWriteStatus(status) {
          * @param props The data for the new model.
          * @returns The newly inserted model's Id.
          * @throws [[IModelError]] if insertion fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.insertModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.insertModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertModel(props) {
             return this._iModel[_implicitTxn].insertModel(props);
@@ -2182,7 +2238,7 @@ function processSchemaWriteStatus(status) {
         /** Update an existing model.
          * @param props the properties of the model to change
          * @throws [[IModelError]] if update fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.updateModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.updateModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateModel(props) {
             this._iModel[_implicitTxn].updateModel(props);
@@ -2194,7 +2250,7 @@ function processSchemaWriteStatus(status) {
          * Cached [Tile]($frontend)s are only invalidated after the geometry guid of the model changes.
          * @note This will throw IModelError with [IModelStatus.VersionTooOld]($core-bentley) if a version of the BisCore schema older than 1.0.11 is present in the iModel.
          * @throws [[IModelError]] if the update fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.updateGeometryGuid instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.updateGeometryGuid instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          * @see [[TxnManager.onModelGeometryChanged]] for the event emitted in response to such a change.
          */
         updateGeometryGuid(modelId) {
@@ -2203,7 +2259,7 @@ function processSchemaWriteStatus(status) {
         /** Delete one or more existing models.
          * @param ids The Ids of the models to be deleted
          * @throws [[IModelError]] if deletion fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.deleteModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.deleteModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteModel(ids) {
             this._iModel[_implicitTxn].deleteModel(ids);
@@ -2427,7 +2483,7 @@ function processSchemaWriteStatus(status) {
          * However when `elProps.federationGuid` is not present or undefined, a new Guid will be generated and stored on the resultant element. But
          * the value of `elProps.federationGuid` is *not* updated. Generally, it is best to re-read the element after inserting (e.g. via [[getElementProps]])
          * if you intend to continue working with it. That will ensure its values reflect the persistent state.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.insertElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.insertElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertElement(elProps, options) {
             return this._iModel[_implicitTxn].insertElement(elProps, options);
@@ -2442,7 +2498,7 @@ function processSchemaWriteStatus(status) {
          * @note The values of `classFullName` and `model` *may not be changed* by this method. Further, it will permute the `elProps` object by adding or
          * overwriting their values to the correct values.
          * @throws [[ITwinError]] if update fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.updateElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.updateElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateElement(elProps) {
             this._iModel[_implicitTxn].updateElement(elProps);
@@ -2451,7 +2507,7 @@ function processSchemaWriteStatus(status) {
          * @param ids The set of Ids of the element(s) to be deleted
          * @throws [[ITwinError]]
          * @see deleteDefinitionElements
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.deleteElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.deleteElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteElement(ids) {
             this._iModel[_implicitTxn].deleteElement(ids);
@@ -2462,7 +2518,7 @@ function processSchemaWriteStatus(status) {
          * @param deleteOptions Options for the delete operation.
          * @returns A result object containing information about the deletion operation success and the element ids that failed to delete (if any).
          * @throws [[ITwinError]] if any of the supplied ids are not well-formed/valid [[Id64String]]s.
-         * @deprecated in 5.1.9 - will not be removed until after 2026-08-15. Use EditTxn.deleteElements instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.1.9 - might be removed in next major version. Use EditTxn.deleteElements instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          * @beta
          */
         deleteElements(ids, deleteOptions) {
@@ -2476,7 +2532,7 @@ function processSchemaWriteStatus(status) {
          * DefinitionElements rather than calling this method separately for each one. Ids that are not valid DefinitionElements will be ignored.
          * @returns An IdSet of the DefinitionElements that are used and were therefore not deleted.
          * @see deleteElement
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.deleteDefinitionElements instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.deleteDefinitionElements instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteDefinitionElements(definitionElementIds) {
             return this._iModel[_implicitTxn].deleteDefinitionElements(definitionElementIds);
@@ -2719,7 +2775,7 @@ function processSchemaWriteStatus(status) {
          * @returns the id of the newly inserted aspect.
          * @note Aspect Ids may collide with element Ids, so don't put both in a container like Set or Map
          *       use [EntityReference]($common) for that instead.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.insertAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.insertAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertAspect(aspectProps) {
             return this._iModel[_implicitTxn].insertAspect(aspectProps);
@@ -2727,7 +2783,7 @@ function processSchemaWriteStatus(status) {
         /** Update an exist ElementAspect within the iModel.
          * @param aspectProps The properties to use to update the ElementAspect.
          * @throws [[IModelError]] if unable to update the ElementAspect.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.updateAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.updateAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateAspect(aspectProps) {
             this._iModel[_implicitTxn].updateAspect(aspectProps);
@@ -2735,7 +2791,7 @@ function processSchemaWriteStatus(status) {
         /** Delete one or more ElementAspects from this iModel.
          * @param aspectInstanceIds The set of instance Ids of the ElementAspect(s) to be deleted
          * @throws [[IModelError]] if unable to delete the ElementAspect.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.deleteAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.deleteAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteAspect(aspectInstanceIds) {
             this._iModel[_implicitTxn].deleteAspect(aspectInstanceIds);
@@ -2744,7 +2800,7 @@ function processSchemaWriteStatus(status) {
          * @param props The properties specifying the element to reparent and its new parent.
          * @throws [[ITwinError]] if the operation fails.
          * @beta
-         * @deprecated in 5.11.0 - will not be removed until after 2026-08-04. Use EditTxn.changeElementParent instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.11.0 - might be removed in next major version. Use EditTxn.changeElementParent instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         changeElementParent(props) {
             this._iModel[_implicitTxn].changeElementParent(props);
@@ -2753,7 +2809,7 @@ function processSchemaWriteStatus(status) {
          * @param props The properties specifying the element to move and its new model.
          * @throws [[ITwinError]] if the operation fails.
          * @beta
-         * @deprecated in 5.11.0 - will not be removed until after 2026-08-04. Use EditTxn.changeElementModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.11.0 - might be removed in next major version. Use EditTxn.changeElementModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         changeElementModel(props) {
             this._iModel[_implicitTxn].changeElementModel(props);
@@ -2812,7 +2868,7 @@ function processSchemaWriteStatus(status) {
             return this._viewStore;
         }
         /**
-         * @beta @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.saveDefaultViewStore instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @beta @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.saveDefaultViewStore instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         saveDefaultViewStore(arg) {
             this._iModel[_implicitTxn].saveDefaultViewStore(arg);
@@ -2830,7 +2886,9 @@ function processSchemaWriteStatus(status) {
                 try {
                     props.push(imodel.elements.getElementProps(id));
                 }
-                catch { }
+                catch {
+                    return;
+                }
             });
             return props;
         }
@@ -2853,7 +2911,9 @@ function processSchemaWriteStatus(status) {
                             break;
                     }
                 }
-                catch { }
+                catch {
+                    continue;
+                }
             }
             return finished;
         }
@@ -3063,9 +3123,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.
@@ -3148,6 +3205,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();
@@ -3160,26 +3219,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
@@ -3199,6 +3265,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");
         }
@@ -3263,6 +3345,7 @@ export class BriefcaseDb extends IModelDb {
         }
         // load all of the settings from workspaces
         await briefcaseDb.loadWorkspaceSettings();
+        await briefcaseDb.initializeSharedElementReservations();
         if (openMode === OpenMode.ReadWrite && CodeService.createForIModel) {
             try {
                 briefcaseDb._codeService = await CodeService.createForIModel(briefcaseDb);
@@ -3318,6 +3401,18 @@ export class BriefcaseDb extends IModelDb {
                     return "foreign key";
             }
         };
+        // `dgn_Domain` holds one bookkeeping row per BIS domain present in the briefcase. The row is
+        // created automatically as soon as the domain's schema is imported, so merging a changeset
+        // that registers a domain inserts a row that was just created locally. Both rows describe the
+        // same domain and the incoming one is authoritative, so this duplicate insert is never fatal.
+        // Only a primary key collision on an insert is benign - an update or delete whose "before"
+        // values do not match (`DbConflictCause.Data`) describes a real divergence and must not be
+        // silently discarded here.
+        if (args.tableName === "dgn_Domain" && args.cause === DbConflictCause.Conflict && args.opcode === DbOpcode.Insert) {
+            Logger.logWarning(category, `${interpretConflictCause(args.cause)} conflict on dgn_Domain - resolved by replacing the existing row with the incoming row`);
+            args.dump();
+            return DbConflictResolution.Replace;
+        }
         if (args.cause === DbConflictCause.Data && !args.indirect) {
             /*
             * From SQLite Docs CHANGESET_DATA as the second argument
@@ -3486,10 +3581,12 @@ 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
+        if (this.reservations.isServerBased !== SchemaSync.isEnabled(this))
+            await this.initializeSharedElementReservations();
         this.txns._onChangesPulled(this.changeset);
     }
     async enableChangesetStatTracking() {
@@ -3569,24 +3666,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.
@@ -3607,7 +3690,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) {
@@ -3678,9 +3761,62 @@ export class BriefcaseDb extends IModelDb {
             await BriefcaseManager.pullMergePush(this, arg);
             this.initializeIModelDb("pullMerge");
         });
+        // If this pull enabled or disabled SchemaSync for this briefcase, its reservations must now be re-initialized
+        if (this.reservations.isServerBased !== SchemaSync.isEnabled(this))
+            await this.initializeSharedElementReservations();
         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();
@@ -3852,6 +3988,7 @@ export class SnapshotDb extends IModelDb {
         const key = CheckpointManager.getKey(checkpoint);
         const db = SnapshotDb.openFile(dbName, { key, container });
         await db.loadWorkspaceSettings();
+        await db.initializeSharedElementReservations();
         return db;
     }
     /** @internal */