@itwin/core-backend 5.13.0-dev.2 → 5.13.0-dev.21

package/lib/esm/IModelDb.js

@@ -8,8 +8,8 @@
 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 { BriefcaseIdValue, Code, DomainOptions, ECJsNames, ECSqlReader, EditTxnError, EntityMetaData, FontMap, IModel, IModelError, IModelNotFoundResponse, ProfileOptions, QueryBinder, QueryRowFormat, resolveNavPropId, SchemaState, ViewStoreError, ViewStoreRpc } from "@itwin/core-common";
+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";
 import { BriefcaseManager } from "./BriefcaseManager";
@@ -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.
@@ -185,12 +189,16 @@ export class IModelDb extends IModel {
     [_implicitTxn];
     /** @internal */
     [_activeTxn];
-    /** Returns the active [[EditTxn]] if one is current, otherwise the implicit transaction.
-     * Use this inside element and relationship callbacks that may be invoked either during an explicit transaction or
-     * during indirect change processing.
-     * @note This method is a temporary workaround until [[OnElementArg]] (and related callback arg types) are updated
-     * to carry the transaction directly in a future PR.
-     * @internal
+    /** Returns the transaction to use for additional edits from an element, model, or aspect callback.
+     * In callbacks whose arguments provide an [[IModelDb]] but no transaction, obtain this transaction through
+     * `arg.iModel.getIndirectTxn()` and pass it to APIs that accept an [[EditTxn]].
+     *
+     * If an explicit transaction is active, this returns that transaction. Otherwise, it returns the implicit transaction
+     * used by legacy write paths. Callbacks that receive an `indirectEditTxn` argument should use that transaction directly.
+     *
+     * @note The operation that invoked the callback owns the transaction. Callback implementations must not invoke transaction
+     * lifecycle methods such as [[EditTxn.start]], [[EditTxn.end]], [[EditTxn.saveChanges]], [[EditTxn.abandonChanges]], or [[EditTxn.onClose]].
+     * @beta
      */
     getIndirectTxn() {
         return this[_activeTxn] ?? this[_implicitTxn];
@@ -199,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
      */
@@ -299,7 +317,9 @@ export class IModelDb extends IModel {
                         db[_nativeDb].abandonChanges();
                         db.close();
                     }
-                    catch { }
+                    catch {
+                        return;
+                    }
                 });
             });
         }
@@ -356,18 +376,29 @@ export class IModelDb extends IModel {
             this.optimize();
         IModelDb._openDbs.delete(this._fileKey);
         this._workspace?.close();
+        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;
@@ -914,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");
@@ -1000,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 {
@@ -1037,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 = {
@@ -2169,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);
@@ -2177,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);
@@ -2189,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) {
@@ -2198,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);
@@ -2422,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);
@@ -2437,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);
@@ -2446,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);
@@ -2457,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) {
@@ -2471,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);
@@ -2574,21 +2635,27 @@ function processSchemaWriteStatus(status) {
             return this._queryAspect(aspectInstanceId, aspectClassFullName);
         }
         static classMap = new Map();
+        getAspectPropsFromInstanceQuery(rawInstance) {
+            const parsedRow = typeof rawInstance === "string" ? JSON.parse(rawInstance, Base64EncodedString.reviver) : rawInstance;
+            if (!JsonUtils.isObject(parsedRow))
+                throw new IModelError(IModelStatus.BadRequest, "Expected an ElementAspect instance query to return an object");
+            const row = {};
+            for (const [key, value] of Object.entries(parsedRow)) {
+                const ecPropertyName = key.length === 0 ? key : key[0].toUpperCase() + key.substring(1);
+                row[ECJsNames.toJsName(ecPropertyName)] = value;
+            }
+            const className = row.className;
+            if (typeof className !== "string")
+                throw new IModelError(IModelStatus.BadRequest, "Expected an ElementAspect instance query to return a className");
+            row.classFullName = className.replace(".", ":"); // add in property required by EntityProps
+            delete row.className; // clear property from SELECT $ that we don't want in the final instance
+            return row;
+        }
         runInstanceQuery(sql, elementId, excludedClassFullNames) {
             return this._iModel.withQueryReader(sql, (reader) => {
                 const aspects = [];
                 for (const queryRow of reader) {
-                    const row = {};
-                    const rawInstance = queryRow[0];
-                    const parsedRow = typeof rawInstance === "string" ? JSON.parse(rawInstance) : rawInstance;
-                    // eslint-disable-next-line guard-for-in
-                    for (const key in parsedRow) {
-                        const jsName = ECJsNames.toJsName(key[0].toUpperCase() + key.substring(1));
-                        Object.defineProperty(row, jsName, { enumerable: true, configurable: true, writable: true, value: parsedRow[key] });
-                    }
-                    const aspectProps = row;
-                    aspectProps.classFullName = aspectProps.className.replace(".", ":"); // add in property required by EntityProps
-                    aspectProps.className = undefined; // clear property from SELECT $ that we don't want in the final instance
+                    const aspectProps = this.getAspectPropsFromInstanceQuery(queryRow[0]);
                     if ((undefined === excludedClassFullNames) || !excludedClassFullNames.has(aspectProps.classFullName))
                         aspects.push(this._iModel.constructEntity(aspectProps));
                 }
@@ -2603,9 +2670,9 @@ function processSchemaWriteStatus(status) {
          */
         getAspects(elementId, aspectClassFullName, excludedClassFullNames) {
             if (aspectClassFullName === undefined) {
-                const allAspects = this.runInstanceQuery(`SELECT $ FROM (
-          SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId
-            UNION ALL
+                const allAspects = this.runInstanceQuery(`SELECT $ FROM (
+          SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId
+            UNION ALL
           SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId) OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`, elementId, excludedClassFullNames);
                 if (allAspects.length === 0)
                     Logger.logInfo(BackendLoggerCategory.ECDb, `No aspects found for class ${aspectClassFullName} and element ${elementId}`);
@@ -2624,7 +2691,7 @@ function processSchemaWriteStatus(status) {
             let classIdList = IModelDb.Elements.classMap.get(aspectClassFullName);
             if (classIdList === undefined) {
                 const classIds = [];
-                const sql = `select SourceECInstanceId from meta.ClassHasAllBaseClasses where TargetECInstanceId = (select ECInstanceId from meta.ECClassDef where Name=:className
+                const sql = `select SourceECInstanceId from meta.ClassHasAllBaseClasses where TargetECInstanceId = (select ECInstanceId from meta.ECClassDef where Name=:className
         and Schema.Id = (select ECInstanceId from meta.ECSchemaDef where Name=:schemaName)) and SourceECInstanceId != TargetECInstanceId`;
                 this._iModel.withQueryReader(sql, (reader) => {
                     for (const row of reader) {
@@ -2643,22 +2710,72 @@ function processSchemaWriteStatus(status) {
                 return [];
             }
             // Execute an instance query to retrieve all aspects from all the derived classes
-            const aspects = this.runInstanceQuery(`SELECT $ FROM (
-        SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
-          UNION ALL
-        SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
+            const aspects = this.runInstanceQuery(`SELECT $ FROM (
+        SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
+          UNION ALL
+        SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
         ) OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`, elementId, excludedClassFullNames);
             if (aspects.length === 0)
                 Logger.logInfo(BackendLoggerCategory.ECDb, `No aspects found for class ${aspectClassFullName} and element ${elementId}`);
             return aspects;
         }
+        /** Stream the [[ElementAspect]] instances owned by a set of elements.
+         *
+         * Use this method instead of calling [[getAspects]] repeatedly when reading aspects for multiple elements or when the result may be large. The query reads all requested owners together and yields each aspect without buffering the complete result set. For a single element with a small result, [[getAspects]] provides a simpler synchronous API.
+         *
+         * The order is unspecified unless [[QueryAspectOptions.groupByOwner]] is true.
+         * @param options Defines the element Ids, class filters, result ordering, and query connection.
+         * @returns An async iterator over the matching aspects.
+         * @beta
+         */
+        async *queryAspects(options) {
+            const elementIds = Id64.toIdSet(options.elementIds);
+            if (elementIds.size === 0)
+                return;
+            const params = new QueryBinder().bindIdSet("elementIds", elementIds);
+            const classFilter = options.aspectClassFullName === undefined ? "" : `AND aspect.ECClassId IN (
+        SELECT SourceECInstanceId FROM meta.ClassHasAllBaseClasses
+        WHERE TargetECInstanceId=ec_classid(:aspectClassFullName)
+      )`;
+            if (options.aspectClassFullName !== undefined)
+                params.bindString("aspectClassFullName", options.aspectClassFullName.replace(".", ":"));
+            const excludedClassIds = [];
+            let excludedClassIndex = 0;
+            for (const classFullName of options.excludedAspectClassFullNames ?? []) {
+                const parameterName = `excludedAspectClass${excludedClassIndex++}`;
+                excludedClassIds.push(`ec_classid(:${parameterName})`);
+                params.bindString(parameterName, classFullName.replace(".", ":"));
+            }
+            const excludedClassFilter = excludedClassIds.length === 0 ? "" : `AND aspect.ECClassId NOT IN (
+        SELECT ECInstanceId FROM meta.ECClassDef WHERE ECInstanceId IN (${excludedClassIds.join(",")})
+      )`;
+            const orderBy = options.groupByOwner
+                ? "ORDER BY OwnerId, AspectKind, ECClassId, ECInstanceId"
+                : "";
+            const sql = `WITH OwnerIds AS (SELECT id FROM IdSet(:elementIds))
+        SELECT $ FROM (
+          SELECT aspect.ECInstanceId, aspect.ECClassId, aspect.Element.Id AS OwnerId, 0 AS AspectKind
+          FROM OwnerIds owners
+          CROSS JOIN Bis.ElementMultiAspect aspect ON aspect.Element.Id=owners.id
+          WHERE TRUE ${classFilter} ${excludedClassFilter}
+          UNION ALL
+          SELECT aspect.ECInstanceId, aspect.ECClassId, aspect.Element.Id AS OwnerId, 1 AS AspectKind
+          FROM OwnerIds owners
+          CROSS JOIN Bis.ElementUniqueAspect aspect ON aspect.Element.Id=owners.id
+          WHERE TRUE ${classFilter} ${excludedClassFilter}
+        ) ${orderBy}
+        OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`;
+            const reader = this._iModel.createQueryReader(sql, params, { usePrimaryConn: options.usePrimaryConn });
+            for await (const queryRow of reader)
+                yield this._iModel.constructEntity(this.getAspectPropsFromInstanceQuery(queryRow[0]));
+        }
         /** Insert a new ElementAspect into the iModel.
          * @param aspectProps The properties of the new ElementAspect.
          * @throws [[IModelError]] if unable to insert the ElementAspect.
          * @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);
@@ -2666,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);
@@ -2674,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);
@@ -2683,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);
@@ -2692,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);
@@ -2711,15 +2828,27 @@ function processSchemaWriteStatus(status) {
         static viewStoreProperty = { namespace: "itwinjs", name: "DefaultViewStore" };
         _viewStore;
         get hasViewStore() { return undefined !== this._viewStore; }
-        /** @beta */
+        /** The [[ViewStore.CloudAccess]] for this iModel.
+         * @note The iModel owns its ViewStore (whether assigned via this setter or created by [[accessViewStore]]): it is closed when the iModel is closed.
+         * @beta
+         */
         get viewStore() {
             if (undefined === this._viewStore)
                 throw new IModelError(IModelStatus.BadRequest, "No ViewStore available");
             return this._viewStore;
         }
         set viewStore(viewStore) {
+            if (this._viewStore !== undefined && this._viewStore !== viewStore)
+                this._viewStore.close();
             this._viewStore = viewStore;
         }
+        /** Close the ViewStore for this iModel, if one is open. Called when the iModel is closed.
+         * @internal
+         */
+        [_close]() {
+            this._viewStore?.close();
+            this._viewStore = undefined;
+        }
         /** @beta */
         async accessViewStore(args) {
             let props = args.props;
@@ -2739,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);
@@ -2757,7 +2886,9 @@ function processSchemaWriteStatus(status) {
                 try {
                     props.push(imodel.elements.getElementProps(id));
                 }
-                catch { }
+                catch {
+                    return;
+                }
             });
             return props;
         }
@@ -2780,7 +2911,9 @@ function processSchemaWriteStatus(status) {
                             break;
                     }
                 }
-                catch { }
+                catch {
+                    continue;
+                }
             }
             return finished;
         }
@@ -2990,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.
@@ -3075,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();
@@ -3087,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
@@ -3126,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");
         }
@@ -3190,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);
@@ -3245,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
@@ -3413,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() {
@@ -3496,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.
@@ -3534,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) {
@@ -3605,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();
@@ -3779,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 */