@itwin/core-backend 5.10.0-dev.9 → 5.10.0

package/lib/cjs/IModelDb.js

@@ -165,6 +165,7 @@ class IModelDb extends core_common_1.IModel {
     _jsClassMap;
     _schemaMap;
     _schemaContext;
+    _schemasPromise;
     /** @deprecated in 5.0.0 - will not be removed until after 2026-06-13. Use [[fonts]]. */
     _fontMap; // eslint-disable-line @typescript-eslint/no-deprecated
     _fonts = (0, IModelDbFontsImpl_1.createIModelDbFonts)(this);
@@ -721,6 +722,7 @@ class IModelDb extends core_common_1.IModel {
         const where = [...parentCategories].join(",");
         const query = `SELECT ECInstanceId as id, Parent.Id as parentId, Properties as appearance FROM BisCore.SubCategory WHERE Parent.Id IN (${where})`;
         try {
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             for await (const row of this.createQueryReader(query, undefined, { rowFormat: core_common_1.QueryRowFormat.UseJsPropertyNames })) {
                 result.push(row.toRow());
             }
@@ -741,6 +743,7 @@ class IModelDb extends core_common_1.IModel {
         const where = [...categoryIds].join(",");
         const query = `SELECT ECInstanceId as id, Parent.Id as parentId, Properties as appearance FROM BisCore.SubCategory WHERE Parent.Id IN (${where})`;
         try {
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             for await (const row of this.createQueryReader(query, undefined, { rowFormat: core_common_1.QueryRowFormat.UseJsPropertyNames })) {
                 result.push(row.toRow());
             }
@@ -797,6 +800,11 @@ class IModelDb extends core_common_1.IModel {
             this._jsClassMap = undefined;
             this._schemaMap = undefined;
             this._schemaContext = undefined;
+            if (this._schemasPromise) {
+                const old = this._schemasPromise;
+                this._schemasPromise = undefined;
+                old.then((view) => view.markOutdated()).catch(() => { });
+            }
             this[Symbols_1._nativeDb].clearECDbCache();
         }
         this.elements[Symbols_1._cache].clear();
@@ -809,7 +817,7 @@ class IModelDb extends core_common_1.IModel {
      * ``` ts
      * [[include:IModelDb.updateProjectExtents]]
      * ```
-     * @deprecated in 5.1.9 - will not be removed until after 2027-05-04. Use EditTxn.updateProjectExtents instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+     * @deprecated in 5.9.0 - will not be removed until after 2027-05-04. Use EditTxn.updateProjectExtents instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     updateProjectExtents(newExtents) {
         this[Symbols_1._implicitTxn].updateProjectExtents(newExtents);
@@ -833,13 +841,13 @@ class IModelDb extends core_common_1.IModel {
         };
     }
     /** Update the [EcefLocation]($docs/learning/glossary#eceflocation) of this iModel.
-     * @deprecated in 5.1.9 - will not be removed until after 2027-05-04. Use EditTxn.updateEcefLocation instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+     * @deprecated in 5.9.0 - will not be removed until after 2027-05-04. Use EditTxn.updateEcefLocation instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     updateEcefLocation(ecef) {
         this[Symbols_1._implicitTxn].updateEcefLocation(ecef);
     }
     /** Update the IModelProps of this iModel in the database.
-     * @deprecated in 5.1.9 - will not be removed until after 2027-05-04. Use EditTxn.updateIModelProps instead, within an explicit EditTxn scope (or via withEditTxn).
+     * @deprecated in 5.9.0 - will not be removed until after 2027-05-04. Use EditTxn.updateIModelProps instead, within an explicit EditTxn scope (or via withEditTxn).
      */
     updateIModelProps() {
         this[Symbols_1._implicitTxn].updateIModelProps();
@@ -848,7 +856,7 @@ class IModelDb extends core_common_1.IModel {
         this[Symbols_1._implicitTxn].saveChanges(descriptionOrArgs);
     }
     /** Abandon changes in memory that have not been saved as a Txn to this iModelDb.
-     * @deprecated in 5.1.9 - will not be removed until after 2027-05-04. Use EditTxn.abandonChanges instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+     * @deprecated in 5.9.0 - will not be removed until after 2027-05-04. Use EditTxn.abandonChanges instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
     */
     abandonChanges() {
         this[Symbols_1._implicitTxn].abandonChanges();
@@ -1237,7 +1245,7 @@ class IModelDb extends core_common_1.IModel {
     }
     /** The registry of entity metadata for this iModel.
      * @internal
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `schemaContext` from the `iModel` instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` from the `iModel` instead.
      *
      * @example
      * ```typescript
@@ -1245,7 +1253,8 @@ class IModelDb extends core_common_1.IModel {
      * const classMetaData: EntityMetaData | undefined = iModel.classMetaDataRegistry.find("SchemaName:ClassName");
      *
      * // Replacement:
-     * const metaData: EntityClass | undefined = imodel.schemaContext.getSchemaItemSync("SchemaName.ClassName", EntityClass);
+     * const view = await imodel.getSchemaView();
+     * const cls = view.findClass("SchemaName:ClassName");
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1272,7 +1281,11 @@ class IModelDb extends core_common_1.IModel {
         return this._schemaMap;
     }
     /**
-     * Gets the context that allows accessing the metadata (ecschema-metadata package) of this iModel
+     * Gets the context that allows accessing the metadata (`@itwin/ecschema-metadata` package) of this iModel.
+     *
+     * For runtime read-only access - class/property iteration, IS-A checks, navigating relationships, KOQ lookups -
+     * prefer [[getSchemaView]]. `schemaContext` remains the right choice when you need schema authoring
+     * (via `@itwin/ecschema-editing`), custom-attribute deserialization, or the full ecschema-metadata object graph.
      * @public @preview
      */
     get schemaContext() {
@@ -1286,6 +1299,55 @@ class IModelDb extends core_common_1.IModel {
         }
         return this._schemaContext;
     }
+    /** Get the schema view for this iModel. The view is built lazily on
+     * first call by fetching compact binary schema data via `PRAGMA schema_view` through
+     * the ConcurrentQuery thread pool. Subsequent calls return the cached view. Multiple
+     * concurrent callers share a single in-flight build.
+     *
+     * The returned `SchemaView` is a lightweight, read-only, synchronous API for
+     * navigating schema metadata - classes, properties, relationships, enumerations, etc.
+     * It is the recommended default for runtime read-only metadata access and is significantly
+     * faster and lower-memory than [[schemaContext]]. Use [[schemaContext]] for schema authoring,
+     * custom-attribute deserialization, or anywhere you need the full ecschema-metadata object graph.
+     * @beta
+     */
+    async getSchemaView() {
+        if (this._schemasPromise) {
+            const ctx = await this._schemasPromise;
+            if (!ctx.isOutdated)
+                return ctx;
+        }
+        // Capture the in-flight promise locally so the rejection handler only clears
+        // `_schemasPromise` if it still points at this build. A concurrent invalidation +
+        // re-fetch could otherwise replace the field before our hydrate fails, and a naive
+        // `_schemasPromise = undefined` would clobber that newer reference.
+        const inflight = this._hydrateSchemas();
+        this._schemasPromise = inflight;
+        inflight.catch(() => {
+            if (this._schemasPromise === inflight)
+                this._schemasPromise = undefined;
+        });
+        return inflight;
+    }
+    async _hydrateSchemas() {
+        // PRAGMA returns exactly one row with format, formatVersion, data (binary), schemaToken.
+        // Important: only call reader.next() once - do NOT use `for await` on PRAGMA results.
+        // ConcurrentQuery wraps regular ECSQL in LIMIT/OFFSET for pagination but skips this for
+        // PRAGMAs. If the serialized result exceeds the memory threshold, the response is marked
+        // "Partial", and a `for await` loop would re-issue the same PRAGMA forever since PRAGMAs
+        // don't support OFFSET-based pagination.
+        // This implementation uses the non-pinned version of the pragma other than frontend - because backend
+        // is always strictly coupled with the native code.
+        const reader = this.createQueryReader("PRAGMA schema_view");
+        const result = await reader.next();
+        if (result.done)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "PRAGMA schema_view returned no rows");
+        const data = result.value.data;
+        const token = result.value.schemaToken;
+        if (data === undefined || data === null)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "PRAGMA schema_view returned null data column");
+        return ecschema_metadata_1.SchemaView.fromBinary(data, token ?? "");
+    }
     /** Get the linkTableRelationships for this IModel */
     get relationships() {
         return this._relationships || (this._relationships = new Relationship_1.Relationships(this));
@@ -1360,7 +1422,7 @@ class IModelDb extends core_common_1.IModel {
     }
     /** Get metadata for a class. This method will load the metadata from the iModel into the cache as a side-effect, if necessary.
      * @throws [[IModelError]] if the metadata cannot be found nor loaded.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `getSchemaItem` from `SchemaContext` class instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and call `view.findClass(...)` instead.
      *
      * @example
      *  * ```typescript
@@ -1368,7 +1430,8 @@ class IModelDb extends core_common_1.IModel {
      * const metaData: EntityMetaData = imodel.getMetaData("SchemaName:ClassName");
      *
      * // Replacement:
-     * const metaData: EntityClass | undefined = imodel.schemaContext.getSchemaItemSync("SchemaName", "ClassName", EntityClass);
+     * const view = await imodel.getSchemaView();
+     * const cls = view.findClass("SchemaName:ClassName");
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1386,7 +1449,7 @@ class IModelDb extends core_common_1.IModel {
         return metadata;
     }
     /** Identical to [[getMetaData]], except it returns `undefined` instead of throwing an error if the metadata cannot be found nor loaded.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `getSchemaItem` from `SchemaContext` class instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and call `view.findClass(...)` instead.
      *
      * @example
      *  * ```typescript
@@ -1394,7 +1457,8 @@ class IModelDb extends core_common_1.IModel {
      * const metaData: EntityMetaData | undefined = imodel.tryGetMetaData("SchemaName:ClassName");
      *
      * // Replacement:
-     * const metaData: EntityClass | undefined = imodel.schemaContext.getSchemaItemSync("SchemaName.ClassName", EntityClass);
+     * const view = await imodel.getSchemaView();
+     * const cls = view.findClass("SchemaName:ClassName");
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1414,7 +1478,7 @@ class IModelDb extends core_common_1.IModel {
      * @param func The callback to be invoked on each property
      * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
      * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `forEachProperty` instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and iterate `view.findClass(classFullName)?.getProperties()` instead.
      *
      * @example
      * ```typescript
@@ -1424,9 +1488,10 @@ class IModelDb extends core_common_1.IModel {
      * }, false);
      *
      * // Replacement:
-     * await IModelDb.forEachProperty(imodel, "TestDomain.TestDomainClass", true, (propName: string, property: Property) => {
-     *   console.log(`Property name: ${propName}, Property type: ${property.propertyType}`);
-     * }, false);
+     * const view = await imodel.getSchemaView();
+     * for (const property of view.findClass("BisCore:Element")?.getProperties() ?? []) {
+     *   console.log(`Property name: ${property.name}, Kind: ${property.kind}`);
+     * }
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1440,7 +1505,7 @@ class IModelDb extends core_common_1.IModel {
      * @param func The callback to be invoked on each property
      * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
      * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `forEachProperty` from `SchemaContext` class instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and iterate `view.findClass(classFullName)?.getProperties()` instead.
      *
      * @example
      * ```typescript
@@ -1450,9 +1515,10 @@ class IModelDb extends core_common_1.IModel {
      * });
      *
      * // Replacement:
-     * imodel.schemaContext.forEachProperty("BisCore:Element", true, (propName: string, property: Property) => {
-     *   console.log(`Property name: ${propName}, Property type: ${property.propertyType}`);
-     * });
+     * const view = await imodel.getSchemaView();
+     * for (const property of view.findClass("BisCore:Element")?.getProperties() ?? []) {
+     *   console.log(`Property name: ${property.name}, Kind: ${property.kind}`);
+     * }
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1576,7 +1642,7 @@ class IModelDb extends core_common_1.IModel {
      * @param prop the FilePropertyProps that describes the new property
      * @param value either a string or a blob to save as the file property
      * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {TxnManager.withIndirectTxnMode}.
-     * @deprecated in 5.1.9 - will not be removed until after 2027-05-04. Use EditTxn.saveFileProperty instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+     * @deprecated in 5.9.0 - will not be removed until after 2027-05-04. Use EditTxn.saveFileProperty instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     saveFileProperty(prop, strValue, blobVal) {
         this[Symbols_1._implicitTxn].saveFileProperty(prop, strValue, blobVal);
@@ -1584,7 +1650,7 @@ class IModelDb extends core_common_1.IModel {
     /** delete a "file property" from this iModel
      * @param prop the FilePropertyProps that describes the property
      * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {TxnManager.withIndirectTxnMode}.
-     * @deprecated in 5.1.9 - will not be removed until after 2027-05-04. Use EditTxn.deleteFileProperty instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+     * @deprecated in 5.9.0 - will not be removed until after 2027-05-04. Use EditTxn.deleteFileProperty instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     deleteFileProperty(prop) {
         this[Symbols_1._implicitTxn].deleteFileProperty(prop);
@@ -1792,14 +1858,14 @@ class IModelDb extends core_common_1.IModel {
      * @param dict The SettingDictionary object to stringify and save.
      * @note All saved `SettingDictionary`s are loaded into [[workspace.settings]] every time an iModel is opened.
      * @see [[Settings.addDictionary]] to register a dictionary for the current session only without persisting it.
-     * @beta @deprecated in 5.1.9 - will not be removed until after 2027-05-04. Use EditTxn.saveSettingDictionary instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+     * @beta @deprecated in 5.9.0 - will not be removed until after 2027-05-04. Use EditTxn.saveSettingDictionary instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     saveSettingDictionary(name, dict) {
         this[Symbols_1._implicitTxn].saveSettingDictionary(name, dict);
     }
     /** Delete a SettingDictionary, previously added with [[saveSettingDictionary]], from this iModel.
      * @param name The name of the dictionary to delete.
-     * @beta @deprecated in 5.1.9 - will not be removed until after 2027-05-04. Use EditTxn.deleteSettingDictionary instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+     * @beta @deprecated in 5.9.0 - will not be removed until after 2027-05-04. Use EditTxn.deleteSettingDictionary instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     deleteSettingDictionary(name) {
         this[Symbols_1._implicitTxn].deleteSettingDictionary(name);
@@ -2089,7 +2155,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.1.9 - 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 - 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.
          */
         insertModel(props) {
             return this._iModel[Symbols_1._implicitTxn].insertModel(props);
@@ -2097,7 +2163,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.1.9 - 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 - 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.
          */
         updateModel(props) {
             this._iModel[Symbols_1._implicitTxn].updateModel(props);
@@ -2109,7 +2175,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.1.9 - 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 - 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.
          * @see [[TxnManager.onModelGeometryChanged]] for the event emitted in response to such a change.
          */
         updateGeometryGuid(modelId) {
@@ -2118,7 +2184,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.1.9 - 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 - 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.
          */
         deleteModel(ids) {
             this._iModel[Symbols_1._implicitTxn].deleteModel(ids);
@@ -2344,7 +2410,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.1.9 - 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 - 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.
          */
         insertElement(elProps, options) {
             return this._iModel[Symbols_1._implicitTxn].insertElement(elProps, options);
@@ -2359,7 +2425,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.1.9 - 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 - 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.
          */
         updateElement(elProps) {
             this._iModel[Symbols_1._implicitTxn].updateElement(elProps);
@@ -2368,11 +2434,23 @@ function processSchemaWriteStatus(status) {
          * @param ids The set of Ids of the element(s) to be deleted
          * @throws [[ITwinError]]
          * @see deleteDefinitionElements
-         * @deprecated in 5.1.9 - 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 - 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.
          */
         deleteElement(ids) {
             this._iModel[Symbols_1._implicitTxn].deleteElement(ids);
         }
+        /**
+         * Delete multiple elements from the iModel.
+         * @param ids The ids of the elements to delete. All ids must be well-formed and valid [[Id64String]]s.
+         * @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.
+         * @beta
+         */
+        deleteElements(ids, deleteOptions) {
+            return this._iModel[Symbols_1._implicitTxn].deleteElements(ids, deleteOptions);
+        }
         /** DefinitionElements can only be deleted if it can be determined that they are not referenced by other Elements.
          * This *usage query* can be expensive since it may involve scanning the GeometryStreams of all GeometricElements.
          * Since [[deleteElement]] does not perform these additional checks, it fails in order to prevent potentially referenced DefinitionElements from being deleted.
@@ -2381,7 +2459,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.1.9 - 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 - 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.
          */
         deleteDefinitionElements(definitionElementIds) {
             return this._iModel[Symbols_1._implicitTxn].deleteDefinitionElements(definitionElementIds);
@@ -2575,7 +2653,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.1.9 - 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 - 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.
          */
         insertAspect(aspectProps) {
             return this._iModel[Symbols_1._implicitTxn].insertAspect(aspectProps);
@@ -2583,7 +2661,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.1.9 - 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 - 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.
          */
         updateAspect(aspectProps) {
             this._iModel[Symbols_1._implicitTxn].updateAspect(aspectProps);
@@ -2591,7 +2669,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.1.9 - 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 - 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.
          */
         deleteAspect(aspectInstanceIds) {
             this._iModel[Symbols_1._implicitTxn].deleteAspect(aspectInstanceIds);
@@ -2638,7 +2716,7 @@ function processSchemaWriteStatus(status) {
             return this._viewStore;
         }
         /**
-         * @beta @deprecated in 5.1.9 - 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 - 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.
          */
         saveDefaultViewStore(arg) {
             this._iModel[Symbols_1._implicitTxn].saveDefaultViewStore(arg);
@@ -3327,7 +3405,63 @@ class BriefcaseDb extends IModelDb {
     async getAllChangesetHealthData() {
         return this[Symbols_1._nativeDb].getAllChangesetHealthData();
     }
-    /** Revert timeline changes and then push resulting changeset */
+    /**
+     * Whether file-based transactions are enabled for this briefcase.
+     *
+     * When enabled, transaction data is stored in separate temporary `.txn` files rather than in the
+     * briefcase's internal transaction table. This avoids SQLite blob size limits and reduces memory
+     * pressure for very large changesets, at the cost of additional disk I/O.
+     * @see [[enableFileBasedTxns]] to enable, [[disableFileBasedTxns]] to disable.
+     * @internal
+     */
+    get isFileBasedTxnsEnabled() {
+        return this[Symbols_1._nativeDb].queryLocalValue("fileBasedTxns") === "1";
+    }
+    /**
+     * Enable file-based transactions for this briefcase.
+     * @throws IModelError with [[ChangeSetStatus.HasUncommittedChanges]] if there are unsaved changes.
+     * @throws IModelError with [[ChangeSetStatus.HasLocalChanges]] if there are pending transactions.
+     * @internal
+     */
+    enableFileBasedTxns() {
+        this._setFileBasedTxnsSetting(true);
+    }
+    /**
+     * Disable file-based transactions for this briefcase, reverting to the default storage mode
+     * (transactions stored within the briefcase's internal transaction table).
+     * @throws IModelError with [[ChangeSetStatus.HasUncommittedChanges]] if there are unsaved changes.
+     * @throws IModelError with [[ChangeSetStatus.HasLocalChanges]] if there are pending transactions.
+     * @internal
+     */
+    disableFileBasedTxns() {
+        this._setFileBasedTxnsSetting(false);
+    }
+    _setFileBasedTxnsSetting(enabled) {
+        if (this.isFileBasedTxnsEnabled === enabled)
+            return;
+        const nativeDb = this[Symbols_1._nativeDb];
+        if (nativeDb.hasUnsavedChanges())
+            throw new core_common_1.IModelError(core_bentley_1.ChangeSetStatus.HasUncommittedChanges, "Cannot change file-based transactions setting while there are unsaved changes");
+        if (nativeDb.hasPendingTxns())
+            throw new core_common_1.IModelError(core_bentley_1.ChangeSetStatus.HasLocalChanges, "Cannot change file-based transactions setting while there are pending transactions");
+        if (enabled)
+            nativeDb.saveLocalValue("fileBasedTxns", "1");
+        else
+            nativeDb.deleteLocalValue("fileBasedTxns");
+    }
+    /**
+     * Revert timeline changes and push the resulting changeset.
+     *
+     * Pulls the latest changes, acquires the schema lock, reverts the inclusive range of
+     * changesets `[toIndex..current]`, and pushes the revert as a new changeset. On failure,
+     * follow the behavior specified by `arg.inCaseOfFailure`, which may discard local changes,
+     * retain local changes, or delete the briefcase.
+     *
+     * @param arg - Arguments specifying the target changeset index, push options, access token, and failure handling behavior.
+     * @throws IModelError with [[ChangeSetStatus.ApplyError]] if `toIndex` is not specified.
+     * @throws IModelError with [[ChangeSetStatus.HasUncommittedChanges]] if there are unsaved changes.
+     * @throws IModelError with [[ChangeSetStatus.HasLocalChanges]] if there are pending transactions.
+     */
     async revertAndPushChanges(arg) {
         const nativeDb = this[Symbols_1._nativeDb];
         if (arg.toIndex === undefined) {
@@ -3359,11 +3493,14 @@ class BriefcaseDb extends IModelDb {
         if (nativeDb.schemaSyncEnabled()) {
             arg.skipSchemaChanges = true;
         }
+        // The native side enables file-based txns during revert. Restore the original setting afterward.
+        const wasFileBasedTxnsEnabled = this.isFileBasedTxnsEnabled;
+        const preRevertIndex = this.changeset.index;
         try {
             await BriefcaseManager_1.BriefcaseManager.revertTimelineChanges(this, arg);
-            this[Symbols_1._nativeDb].saveChanges("Revert changes");
+            nativeDb.saveChanges("Revert changes");
             if (!arg.description) {
-                arg.description = `Reverted changes from ${this.changeset.index} to ${arg.toIndex}${arg.skipSchemaChanges ? " (schema changes skipped)" : ""}`;
+                arg.description = `Reverted changes from ${preRevertIndex} to ${arg.toIndex}${arg.skipSchemaChanges ? " (schema changes skipped)" : ""}`;
             }
             const pushArgs = {
                 description: arg.description,
@@ -3378,13 +3515,49 @@ class BriefcaseDb extends IModelDb {
             this.clearCaches();
         }
         catch (err) {
-            if (!arg.retainLocks) {
-                await this.locks.releaseAllLocks();
-                throw err;
+            const failureAction = arg.inCaseOfFailure ?? "revert";
+            try {
+                switch (failureAction) {
+                    case "revert":
+                        // Restore the briefcase to its pre-revert state: save any unsaved changes into txns,
+                        // reverse all txns, then delete them.
+                        nativeDb.saveChanges();
+                        if (nativeDb.hasPendingTxns())
+                            nativeDb.reverseAll();
+                        nativeDb.deleteAllTxns();
+                        break;
+                    case "delete":
+                        // Clear local changes first so lock release can succeed.
+                        nativeDb.abandonChanges();
+                        nativeDb.deleteAllTxns();
+                        if (!arg.retainLocks)
+                            await this.locks.releaseAllLocks();
+                        const filePath = this.pathName;
+                        this.close();
+                        await BriefcaseManager_1.BriefcaseManager.deleteBriefcaseFiles(filePath, arg.accessToken);
+                        break;
+                    case "retain":
+                        // Keep local changes as-is for caller inspection/recovery.
+                        nativeDb.saveChanges();
+                        break;
+                }
+            }
+            catch (cleanupErr) {
+                core_bentley_1.Logger.logError(loggerCategory, `Failed to clean up after revert error (action=${failureAction}): ${String(cleanupErr)}`);
             }
+            if (!arg.retainLocks && this.isOpen) {
+                try {
+                    await this.locks.releaseAllLocks();
+                }
+                catch (lockErr) {
+                    core_bentley_1.Logger.logError(loggerCategory, `Failed to release locks after revert failure (action=${failureAction}): ${String(lockErr)}`);
+                }
+            }
+            throw err;
         }
         finally {
-            this[Symbols_1._nativeDb].abandonChanges();
+            if (this.isOpen && !wasFileBasedTxnsEnabled && !nativeDb.hasPendingTxns() && !nativeDb.hasUnsavedChanges())
+                this.disableFileBasedTxns();
         }
     }
     /**