@itwin/core-backend 5.13.0-dev.9 → 5.13.1

package/lib/cjs/IModelDb.js

@@ -48,7 +48,9 @@ const WorkspaceImpl_1 = require("./internal/workspace/WorkspaceImpl");
 const SettingsImpl_1 = require("./internal/workspace/SettingsImpl");
 const NativePlatform_1 = require("./internal/NativePlatform");
 const NoLocks_1 = require("./internal/NoLocks");
+const NoReservations_1 = require("./internal/NoReservations");
 const IModelDbFontsImpl_1 = require("./internal/IModelDbFontsImpl");
+const SchemaSyncReservations_1 = require("./internal/SchemaSyncReservations");
 const Symbols_1 = require("./internal/Symbols");
 const ecschema_metadata_1 = require("@itwin/ecschema-metadata");
 const Schema_1 = require("./Schema");
@@ -178,6 +180,8 @@ class IModelDb extends core_common_1.IModel {
     /** @internal */
     _locks = (0, NoLocks_1.createNoOpLockControl)();
     /** @internal */
+    _reservations = (0, NoReservations_1.createNoOpReservations)();
+    /** @internal */
     _codeService;
     /**
      * The always-available implicit transaction for this iModel.
@@ -206,6 +210,16 @@ class IModelDb extends core_common_1.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?.[Symbols_1._close]();
+        if (SchemaSync_1.SchemaSync.isEnabled(this))
+            this._reservations = await (0, SchemaSyncReservations_1.createSchemaSyncReservations)(this);
+        else
+            this._reservations = (0, NoReservations_1.createNoOpReservations)();
+    }
     /** Provides methods for interacting with [font-related information]($docs/learning/backend/Fonts.md) stored in this iModel.
      * @beta
      */
@@ -306,7 +320,9 @@ class IModelDb extends core_common_1.IModel {
                         db[Symbols_1._nativeDb].abandonChanges();
                         db.close();
                     }
-                    catch { }
+                    catch {
+                        return;
+                    }
                 });
             });
         }
@@ -366,16 +382,26 @@ class IModelDb extends core_common_1.IModel {
         this.views[Symbols_1._close]();
         this.locks[Symbols_1._close]();
         this._locks = undefined;
+        this.reservations[Symbols_1._close]();
+        this._reservations = undefined;
         this._codeService?.close();
         this._codeService = undefined;
         this[Symbols_1._nativeDb].closeFile();
     }
+    /**
+     * Save any unsaved schema changes in this iModel.
+     * @internal
+    */
     saveSchemaChanges(args) {
         if (!this[Symbols_1._nativeDb].hasUnsavedChanges())
             return;
         const saveArgs = typeof args === "string" ? { description: args } : args;
         saveArgs === undefined ? this[Symbols_1._nativeDb].saveChanges() : this[Symbols_1._nativeDb].saveChanges(JSON.stringify(saveArgs));
     }
+    /**
+     * Abandon any unsaved schema changes in this iModel.
+     * @internal
+     */
     abandonSchemaChanges() {
         if (!this[Symbols_1._nativeDb].hasUnsavedChanges())
             return;
@@ -922,7 +948,7 @@ class IModelDb extends core_common_1.IModel {
     async dropSchemas(schemaNames) {
         if (schemaNames.length === 0)
             return;
-        if (this[Symbols_1._nativeDb].schemaSyncEnabled())
+        if (SchemaSync_1.SchemaSync.isEnabled(this))
             throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot drop schemas when schema sync is enabled");
         if (this[Symbols_1._nativeDb].hasUnsavedChanges())
             throw new core_common_1.IModelError(core_bentley_1.ChangeSetStatus.HasUncommittedChanges, "Cannot drop schemas with unsaved changes");
@@ -1008,26 +1034,34 @@ class IModelDb extends core_common_1.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 core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas while rebasing");
-            }
-            if (this.txns.isIndirectChanges) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas while in an indirect change scope");
-            }
-            // Additional checks when semantic rebase is enabled
-            if (IModelHost_1.IModelHost.useSemanticRebase) {
-                if (this[Symbols_1._nativeDb].hasUnsavedChanges()) {
-                    throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas with unsaved changes when useSemanticRebase flag is on");
-                }
-                if (this[Symbols_1._nativeDb].schemaSyncEnabled()) {
-                    throw new core_common_1.IModelError(core_bentley_1.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 core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas while rebasing");
+        }
+        if (this.txns.isIndirectChanges) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas while in an indirect change scope");
+        }
+        // Additional checks when semantic rebase is enabled
+        if (IModelHost_1.IModelHost.useSemanticRebase) {
+            if (this[Symbols_1._nativeDb].hasUnsavedChanges()) {
+                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas with unsaved changes when useSemanticRebase flag is on");
+            }
+            if (SchemaSync_1.SchemaSync.isEnabled(this)) {
+                throw new core_common_1.IModelError(core_bentley_1.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 {
@@ -1045,30 +1079,52 @@ class IModelDb extends core_common_1.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[Symbols_1._nativeDb].schemaSyncEnabled()) {
-            await SchemaSync_1.SchemaSync.withLockedAccess(this, { openMode: core_bentley_1.OpenMode.Readonly, operationName: "schema sync" }, async (syncAccess) => {
-                const schemaSyncDbUri = syncAccess.getUri();
-                this.saveSchemaChanges();
-                try {
-                    nativeImportOp(schemas, { schemaLockHeld: false, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
-                }
-                catch (outerErr) {
-                    if (core_bentley_1.DbResult.BE_SQLITE_ERROR_DataTransformRequired === outerErr.errorNumber) {
-                        this.abandonSchemaChanges();
-                        if (this[Symbols_1._nativeDb].getITwinId() !== core_bentley_1.Guid.empty)
-                            await this.acquireSchemaLock();
-                        try {
-                            nativeImportOp(schemas, { schemaLockHeld: true, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
-                        }
-                        catch (innerErr) {
-                            throw new core_common_1.IModelError(innerErr.errorNumber, innerErr.message);
-                        }
+        if (SchemaSync_1.SchemaSync.isEnabled(this)) {
+            // The shared lock lets concurrent updates through while blocking anyone taking the exclusive lock for an upgrade.
+            if (this[Symbols_1._nativeDb].getITwinId() !== core_bentley_1.Guid.empty)
+                await this.locks.acquireLocks({ shared: core_common_1.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_1.SchemaSync.withLockedAccess(this, { openMode: core_bentley_1.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 core_common_1.IModelError(outerErr.errorNumber, outerErr.message);
+                    catch (err) {
+                        if (SchemaSync_1.SchemaSync.requiresUpgrade(err))
+                            throw new core_common_1.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 core_common_1.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[Symbols_1._nativeDb].cancelTo(txnBeforeAdopt, true);
+                    if (core_bentley_1.IModelStatus.Success !== status)
+                        core_bentley_1.Logger.logError(loggerCategory, `Failed to roll back the adopted schema rows after a failed import: ${core_bentley_1.IModelStatus[status] ?? status}`);
                 }
-            });
+                throw err;
+            }
         }
         else {
             const nativeImportOptions = {
@@ -2178,7 +2234,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[Symbols_1._implicitTxn].insertModel(props);
@@ -2186,7 +2242,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[Symbols_1._implicitTxn].updateModel(props);
@@ -2198,7 +2254,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) {
@@ -2207,7 +2263,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[Symbols_1._implicitTxn].deleteModel(ids);
@@ -2431,7 +2487,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[Symbols_1._implicitTxn].insertElement(elProps, options);
@@ -2446,7 +2502,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[Symbols_1._implicitTxn].updateElement(elProps);
@@ -2455,7 +2511,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[Symbols_1._implicitTxn].deleteElement(ids);
@@ -2466,7 +2522,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) {
@@ -2480,7 +2536,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[Symbols_1._implicitTxn].deleteDefinitionElements(definitionElementIds);
@@ -2723,7 +2779,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[Symbols_1._implicitTxn].insertAspect(aspectProps);
@@ -2731,7 +2787,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[Symbols_1._implicitTxn].updateAspect(aspectProps);
@@ -2739,7 +2795,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[Symbols_1._implicitTxn].deleteAspect(aspectInstanceIds);
@@ -2748,7 +2804,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[Symbols_1._implicitTxn].changeElementParent(props);
@@ -2757,7 +2813,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[Symbols_1._implicitTxn].changeElementModel(props);
@@ -2816,7 +2872,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[Symbols_1._implicitTxn].saveDefaultViewStore(arg);
@@ -2834,7 +2890,9 @@ function processSchemaWriteStatus(status) {
                 try {
                     props.push(imodel.elements.getElementProps(id));
                 }
-                catch { }
+                catch {
+                    return;
+                }
             });
             return props;
         }
@@ -2857,7 +2915,9 @@ function processSchemaWriteStatus(status) {
                             break;
                     }
                 }
-                catch { }
+                catch {
+                    continue;
+                }
             }
             return finished;
         }
@@ -3067,9 +3127,6 @@ 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.
@@ -3152,6 +3209,8 @@ 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();
@@ -3164,26 +3223,33 @@ class BriefcaseDb extends IModelDb {
             wasChanges = nativeDb.hasPendingTxns();
             nativeDb.closeFile();
         };
-        const isSchemaSyncEnabled = await withBriefcaseDb(briefcase, async (db) => {
-            await SchemaSync_1.SchemaSync.pull(db);
-            return db[Symbols_1._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_1.SchemaSync.isEnabled(briefcase)) {
+            await withBriefcaseDb(briefcase, async (db) => SchemaSync_1.SchemaSync.updateDbSchema(db));
             await SchemaSync_1.SchemaSync.withLockedAccess(briefcase, { openMode: core_bentley_1.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[Symbols_1._nativeDb].schemaSyncPush(schemaSyncDbUri);
+                    db[Symbols_1._nativeDb].schemaSyncOverwrite(schemaSyncDbUri);
                     db[Symbols_1._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
@@ -3203,6 +3269,22 @@ 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_1.SchemaSync.isEnabled(briefcase)) {
+            try {
+                await withBriefcaseDb(briefcase, async (db) => {
+                    if (!db.locks.isServerBased)
+                        throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot upgrade schemas with SchemaSync without server-based locking");
+                    await db.acquireSchemaLock();
+                });
+                await this.doUpgrade(briefcase, { profile: core_common_1.ProfileOptions.Upgrade, schemaLockHeld: true }, "Upgraded profile");
+                await this.doUpgrade(briefcase, { domain: core_common_1.DomainOptions.Upgrade, schemaLockHeld: true }, "Upgraded domain schemas");
+            }
+            finally {
+                await withBriefcaseDb(briefcase, async (db) => db.locks[Symbols_1._releaseAllLocks]());
+            }
+            return;
+        }
         try {
             await this.doUpgrade(briefcase, { profile: core_common_1.ProfileOptions.Upgrade }, "Upgraded profile");
         }
@@ -3267,6 +3349,7 @@ class BriefcaseDb extends IModelDb {
         }
         // load all of the settings from workspaces
         await briefcaseDb.loadWorkspaceSettings();
+        await briefcaseDb.initializeSharedElementReservations();
         if (openMode === core_bentley_1.OpenMode.ReadWrite && CodeService_1.CodeService.createForIModel) {
             try {
                 briefcaseDb._codeService = await CodeService_1.CodeService.createForIModel(briefcaseDb);
@@ -3322,6 +3405,18 @@ 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 === core_bentley_1.DbConflictCause.Conflict && args.opcode === core_bentley_1.DbOpcode.Insert) {
+            core_bentley_1.Logger.logWarning(category, `${interpretConflictCause(args.cause)} conflict on dgn_Domain - resolved by replacing the existing row with the incoming row`);
+            args.dump();
+            return core_bentley_1.DbConflictResolution.Replace;
+        }
         if (args.cause === core_bentley_1.DbConflictCause.Data && !args.indirect) {
             /*
             * From SQLite Docs CHANGESET_DATA as the second argument
@@ -3490,10 +3585,12 @@ class BriefcaseDb extends IModelDb {
     async pullChanges(arg) {
         await this.executeWritable(async () => {
             await BriefcaseManager_1.BriefcaseManager.pullAndApplyChangesets(this, arg ?? {});
-            if (!this.skipSyncSchemasOnPullAndPush)
-                await SchemaSync_1.SchemaSync.pull(this);
+            SchemaSync_1.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_1.SchemaSync.isEnabled(this))
+            await this.initializeSharedElementReservations();
         this.txns._onChangesPulled(this.changeset);
     }
     async enableChangesetStatTracking() {
@@ -3573,24 +3670,10 @@ class BriefcaseDb extends IModelDb {
         if (nativeDb.hasPendingTxns()) {
             throw new core_common_1.IModelError(core_bentley_1.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_1.SchemaSync.isEnabled(this)) {
             arg.skipSchemaChanges = true;
         }
         // The native side enables file-based txns during revert. Restore the original setting afterward.
@@ -3611,7 +3694,7 @@ class BriefcaseDb extends IModelDb {
                 pushRetryDelay: arg.pushRetryDelay,
                 retainLocks: arg.retainLocks,
             };
-            await skipSchemaSyncPull(async () => this.pushChanges(pushArgs));
+            await this.pushChanges(pushArgs);
             this.clearCaches();
         }
         catch (err) {
@@ -3682,9 +3765,62 @@ class BriefcaseDb extends IModelDb {
             await BriefcaseManager_1.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_1.SchemaSync.isEnabled(this))
+            await this.initializeSharedElementReservations();
         this.txns._onChangesPushed(this.changeset);
         BriefcaseManager_1.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[Symbols_1._nativeDb].importSchemas(schemas, importOptions));
+    }
+    /** The [[importSchemaStrings]] counterpart of [[upgradeSchemas]].
+     * @alpha
+     */
+    async upgradeSchemaStrings(serializedXmlSchemas, arg) {
+        return this.upgradeSchemasInternal(serializedXmlSchemas, arg, (schemas, importOptions) => this[Symbols_1._nativeDb].importXmlSchemas(schemas, importOptions));
+    }
+    async upgradeSchemasInternal(schemas, arg, nativeImportOp) {
+        if (schemas.length === 0)
+            return;
+        this.assertCanImportSchemas();
+        if (this[Symbols_1._nativeDb].hasUnsavedChanges() || this.txns.hasLocalChanges)
+            throw new core_common_1.IModelError(core_bentley_1.ChangeSetStatus.HasLocalChanges, "Cannot upgrade schemas while there are local changes");
+        if (SchemaSync_1.SchemaSync.isEnabled(this) && !this.locks.isServerBased)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot upgrade schemas with SchemaSync without server-based locking");
+        await this.acquireSchemaLock();
+        await this.pullChanges({ accessToken: arg.accessToken });
+        if (!SchemaSync_1.SchemaSync.isEnabled(this)) {
+            await this.importSchemasInternal(schemas, { ecSchemaXmlContext: arg.ecSchemaXmlContext }, nativeImportOp);
+            await this.pushChanges(arg);
+            return;
+        }
+        await SchemaSync_1.SchemaSync.withLockedAccess(this, { openMode: core_bentley_1.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 core_common_1.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[Symbols_1._nativeDb].abandonChanges();
@@ -3857,6 +3993,7 @@ class SnapshotDb extends IModelDb {
         const key = CheckpointManager_1.CheckpointManager.getKey(checkpoint);
         const db = SnapshotDb.openFile(dbName, { key, container });
         await db.loadWorkspaceSettings();
+        await db.initializeSharedElementReservations();
         return db;
     }
     /** @internal */