@itwin/core-backend 5.9.0-dev.3 → 5.9.0-dev.5

package/lib/esm/IModelDb.js

@@ -9,7 +9,7 @@ import * as fs from "fs";
 import { join } from "path";
 import * as touch from "touch";
 import { assert, BeEvent, BentleyStatus, ChangeSetStatus, DbChangeStage, DbConflictCause, DbConflictResolution, DbResult, Guid, Id64, IModelStatus, JsonUtils, Logger, LogLevel, LRUMap, OpenMode } from "@itwin/core-bentley";
-import { BriefcaseIdValue, Code, DomainOptions, ECJsNames, ECSqlReader, EntityMetaData, FontMap, IModel, IModelError, IModelNotFoundResponse, ProfileOptions, QueryRowFormat, SchemaState, ViewStoreError, ViewStoreRpc } from "@itwin/core-common";
+import { BriefcaseIdValue, Code, DomainOptions, ECJsNames, ECSqlReader, EditTxnError, EntityMetaData, FontMap, IModel, IModelError, IModelNotFoundResponse, ProfileOptions, QueryRowFormat, SchemaState, ViewStoreError, ViewStoreRpc } from "@itwin/core-common";
 import { Range2d, Range3d } from "@itwin/core-geometry";
 import { BackendLoggerCategory } from "./BackendLoggerCategory";
 import { BriefcaseManager } from "./BriefcaseManager";
@@ -35,6 +35,7 @@ import { SchemaSync } from "./SchemaSync";
 import { createServerBasedLocks } from "./internal/ServerBasedLocks";
 import { SqliteStatement, StatementCache } from "./SqliteStatement";
 import { TxnManager } from "./TxnManager";
+import { EditTxn } from "./EditTxn";
 import { DrawingViewDefinition, SheetViewDefinition, ViewDefinition } from "./ViewDefinition";
 import { ViewStore } from "./ViewStore";
 import { SettingsPriority } from "./workspace/Settings";
@@ -44,7 +45,7 @@ import { SettingsImpl } from "./internal/workspace/SettingsImpl";
 import { IModelNative } from "./internal/NativePlatform";
 import { createNoOpLockControl } from "./internal/NoLocks";
 import { createIModelDbFonts } from "./internal/IModelDbFontsImpl";
-import { _cache, _close, _hubAccess, _instanceKeyCache, _nativeDb, _releaseAllLocks, _resetIModelDb } from "./internal/Symbols";
+import { _activeTxn, _cache, _close, _hubAccess, _implicitTxn, _instanceKeyCache, _nativeDb, _releaseAllLocks, _resetIModelDb } from "./internal/Symbols";
 import { ECVersion, SchemaContext, SchemaJsonLocater } from "@itwin/ecschema-metadata";
 import { SchemaMap } from "./Schema";
 import { ElementLRUCache, InstanceKeyLRUCache } from "./internal/ElementLRUCache";
@@ -54,6 +55,38 @@ import { integrityCheckTypeMap, performQuickIntegrityCheck, performSpecificInteg
 import { ECSqlSyncReader } from "./ECSqlSyncReader";
 // spell:ignore fontid fontmap
 const loggerCategory = BackendLoggerCategory.IModelDb;
+/**
+ * Internal write surface used to preserve legacy implicit-transaction mutators while callers migrate to explicit [[EditTxn]] scopes.
+ *
+ * Unlike an explicit [[EditTxn]], this transaction is always available for writable iModels and cannot be manually started or ended.
+ * When implicit-write enforcement is enabled, attempts to write through this transaction are logged or rejected.
+ */
+class ImplicitWriteTxn extends EditTxn {
+    constructor(iModel) {
+        super(iModel, "implicit");
+    }
+    start() {
+        throw new Error("ImplicitWriteTxn cannot be started");
+    }
+    end(_mode = "save", _args) {
+        throw new Error("ImplicitWriteTxn cannot be ended");
+    }
+    verifyWriteable() {
+        const enforcement = EditTxn.implicitWriteEnforcement;
+        if (enforcement === "allow")
+            return;
+        try {
+            EditTxnError.throwError("implicit-txn-write-disallowed", "Implicit transaction write is disallowed. Use an explicit EditTxn instead", this.iModel.key);
+        }
+        catch (err) {
+            if (enforcement === "log") {
+                Logger.logError(loggerCategory, err);
+                return;
+            }
+            throw err;
+        }
+    }
+}
 /** @internal */
 export var BriefcaseLocalValue;
 (function (BriefcaseLocalValue) {
@@ -139,6 +172,25 @@ export class IModelDb extends IModel {
     _locks = createNoOpLockControl();
     /** @internal */
     _codeService;
+    /**
+     * The always-available implicit transaction for this iModel.
+     *
+     * Legacy mutating APIs route through this transaction for backwards compatibility until they are fully migrated to explicit [[EditTxn]] usage.
+     * @internal
+     */
+    [_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
+     */
+    getIndirectTxn() {
+        return this[_activeTxn] ?? this[_implicitTxn];
+    }
     /** @alpha */
     get codeService() { return this._codeService; }
     /** The [[LockControl]] that orchestrates [concurrent editing]($docs/learning/backend/ConcurrencyControl.md) of this iModel. */
@@ -227,17 +279,20 @@ export class IModelDb extends IModel {
         // Make closeIModel available so their code doesn't break.
         this[_nativeDb].closeIModel = () => {
             if (!this.isReadonly)
-                this.saveChanges(); // preserve old behavior of closeIModel that was removed when renamed to closeFile
+                this[_nativeDb].saveChanges(); // preserve old behavior of closeIModel that was removed when renamed to closeFile
+            this[_activeTxn] = undefined;
             this[_nativeDb].closeFile();
         };
         this[_nativeDb].setIModelDb(this);
         this[_resetIModelDb]();
         IModelDb._openDbs.set(this._fileKey, this);
+        this[_implicitTxn] = new ImplicitWriteTxn(this);
+        this[_activeTxn] = undefined;
         if (undefined === IModelDb._shutdownListener) { // the first time we create an IModelDb, add a listener to close any orphan files at shutdown.
             IModelDb._shutdownListener = IModelHost.onBeforeShutdown.addListener(() => {
                 IModelDb._openDbs.forEach((db) => {
                     try {
-                        db.abandonChanges();
+                        db[_nativeDb].abandonChanges();
                         db.close();
                     }
                     catch { }
@@ -267,8 +322,8 @@ export class IModelDb extends IModel {
     }
     /**
      * Detach the attached file from this connection. The attached file is closed and its schemas are unregistered.
-     * @note There are some reserve tablespace names that cannot be used. They are 'main', 'schema_sync_db', 'ecchange' & 'temp'
-     * @param alias identifer that was used in the call to [[attachDb]]
+     * @note There are some reserved table names that cannot be used. They are 'main', 'schema_sync_db', 'ecchange' & 'temp'
+     * @param alias identifier that was used in the call to [[attachDb]]
      *
      * @example [[include:IModelDb_attachDb.code]]
      *
@@ -286,7 +341,13 @@ export class IModelDb extends IModel {
     close(options) {
         if (!this.isOpen)
             return; // don't continue if already closed
+        // Give the active txn a chance to save or abandon before beforeClose() cleanup runs.
+        // StandaloneDb.beforeClose() saves any unsaved changes, so onClose() must run first so
+        // subclasses that override onClose() to abandon changes can do so before that save.
+        if (!this.isReadonly)
+            (this[_activeTxn] ?? this[_implicitTxn]).onClose();
         this.beforeClose();
+        this[_activeTxn] = undefined;
         if (options?.optimize)
             this.optimize();
         IModelDb._openDbs.delete(this._fileKey);
@@ -295,10 +356,20 @@ export class IModelDb extends IModel {
         this._locks = undefined;
         this._codeService?.close();
         this._codeService = undefined;
-        if (!this.isReadonly)
-            this.saveChanges();
         this[_nativeDb].closeFile();
     }
+    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));
+    }
+    abandonSchemaChanges() {
+        if (!this[_nativeDb].hasUnsavedChanges())
+            return;
+        this.clearCaches({ instanceCachesOnly: true });
+        this[_nativeDb].abandonChanges();
+    }
     /** Optimize this iModel by vacuuming, and analyzing.
      *
      * @note This operation requires exclusive access to the database and may take some time on large files.
@@ -735,10 +806,10 @@ export class IModelDb extends IModel {
      * ``` ts
      * [[include:IModelDb.updateProjectExtents]]
      * ```
+     * @deprecated Use EditTxn.updateProjectExtents instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     updateProjectExtents(newExtents) {
-        this.projectExtents = newExtents;
-        this.updateIModelProps();
+        this[_implicitTxn].updateProjectExtents(newExtents);
     }
     /** Compute an appropriate project extents for this iModel based on the ranges of all spatial elements.
      * Typically, the result is simply the union of the ranges of all spatial elements. However, the algorithm also detects "outlier elements",
@@ -758,45 +829,26 @@ export class IModelDb extends IModel {
             outliers: result.outliers,
         };
     }
-    /** Update the [EcefLocation]($docs/learning/glossary#eceflocation) of this iModel.  */
+    /** Update the [EcefLocation]($docs/learning/glossary#eceflocation) of this iModel.
+     * @deprecated Use EditTxn.updateEcefLocation instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+     */
     updateEcefLocation(ecef) {
-        this.setEcefLocation(ecef);
-        this.updateIModelProps();
+        this[_implicitTxn].updateEcefLocation(ecef);
     }
-    /** Update the IModelProps of this iModel in the database. */
+    /** Update the IModelProps of this iModel in the database.
+     * @deprecated Use EditTxn.updateIModelProps instead, within an explicit EditTxn scope (or via withEditTxn).
+     */
     updateIModelProps() {
-        this[_nativeDb].updateIModelProps(this.toJSON());
+        this[_implicitTxn].updateIModelProps();
     }
-    /** Commit unsaved changes in memory as a Txn to this iModelDb.
-     * @internal
-     * @param descriptionOrArgs Optionally provide description or [[SaveChangesArgs]] args for the changes.
-     * @throws [[IModelError]] if there is a problem saving changes or if there are pending, un-processed lock or code requests.
-     * @note This will not push changes to the iModelHub.
-     * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync}, {TxnManager.withIndirectTxnMode} or {RebaseHandler.recompute}.
-     * @see [[IModelDb.pushChanges]] to push changes to the iModelHub.
-     */
     saveChanges(descriptionOrArgs) {
-        if (this.openMode === OpenMode.Readonly)
-            throw new IModelError(IModelStatus.ReadOnly, "IModelDb was opened read-only");
-        if (this.isBriefcaseDb()) {
-            if (this.txns.isIndirectChanges) {
-                throw new IModelError(IModelStatus.BadRequest, "Cannot save changes while in an indirect change scope");
-            }
-        }
-        const args = typeof descriptionOrArgs === "string" ? { description: descriptionOrArgs } : descriptionOrArgs;
-        const stat = this[_nativeDb].saveChanges(args ? JSON.stringify(args) : undefined);
-        if (DbResult.BE_SQLITE_ERROR_PropagateChangesFailed === stat)
-            throw new IModelError(stat, `Could not save changes due to propagation failure.`);
-        if (DbResult.BE_SQLITE_OK !== stat)
-            throw new IModelError(stat, `Could not save changes (${args?.description})`);
+        this[_implicitTxn].saveChanges(descriptionOrArgs);
     }
     /** Abandon changes in memory that have not been saved as a Txn to this iModelDb.
-     * @note This will not delete Txns that have already been saved, even if they have not yet been pushed.
+     * @deprecated Use EditTxn.abandonChanges instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
     */
     abandonChanges() {
-        // Clears instanceKey caches only, instead of all of the backend caches, since the changes are not saved yet
-        this.clearCaches({ instanceCachesOnly: true });
-        this[_nativeDb].abandonChanges();
+        this[_implicitTxn].abandonChanges();
     }
     /**
      * Save all changes and perform a [checkpoint](https://www.sqlite.org/c3ref/wal_checkpoint_v2.html) on this IModelDb.
@@ -808,7 +860,7 @@ export class IModelDb extends IModel {
      */
     performCheckpoint() {
         if (!this.isReadonly) {
-            this.saveChanges();
+            this[_nativeDb].saveChanges();
             this.clearCaches();
             this[_nativeDb].concurrentQueryShutdown();
             this[_nativeDb].performCheckpoint();
@@ -847,7 +899,7 @@ export class IModelDb extends IModel {
      *
      * If the removal was successful, the database is automatically saved to disk.
      * @param schemaNames Array of schema names to drop
-     * @throws [IModelError]($common) if the database if the operation failed.
+     * @throws [[IModelError]] if the operation fails.
      * @alpha
      */
     async dropSchemas(schemaNames) {
@@ -861,11 +913,11 @@ export class IModelDb extends IModel {
             await this.acquireSchemaLock();
         try {
             this[_nativeDb].dropSchemas(schemaNames);
-            this.saveChanges(`dropped unused schemas`);
+            this.saveSchemaChanges("dropped unused schemas");
         }
         catch (error) {
             Logger.logError(loggerCategory, `Failed to drop schemas: ${error}`);
-            this.abandonChanges();
+            this.abandonSchemaChanges();
             throw new IModelError(DbResult.BE_SQLITE_ERROR, `Failed to drop schemas: ${error}`);
         }
         finally {
@@ -890,8 +942,9 @@ export class IModelDb extends IModel {
             transformStrategy: DataTransformationStrategy.None,
         };
         try {
-            if (callback?.preSchemaImportCallback) {
-                const callbackResult = await callback.preSchemaImportCallback(context);
+            const preSchemaImportCallback = callback?.preSchemaImportCallback;
+            if (preSchemaImportCallback) {
+                const callbackResult = await preSchemaImportCallback(context);
                 callbackResources.transformStrategy = callbackResult.transformStrategy;
                 if (callbackResult.transformStrategy === DataTransformationStrategy.Snapshot) {
                     // Create temporary snapshot file
@@ -904,13 +957,12 @@ export class IModelDb extends IModel {
                     }
                     callbackResources.cachedData = callbackResult.cachedData;
                 }
-                if (this.isBriefcaseDb() && IModelHost.useSemanticRebase) {
-                    this.saveChanges("Save changes from schema import pre callback");
-                }
+                if (this.isBriefcaseDb() && IModelHost.useSemanticRebase)
+                    this.saveSchemaChanges("Save changes from schema import pre callback");
             }
         }
         catch (callbackError) {
-            this.abandonChanges();
+            this.abandonSchemaChanges();
             this.cleanupSnapshot(callbackResources);
             throw new IModelError(callbackError.errorNumber ?? IModelStatus.BadRequest, `Failed to execute preSchemaImportCallback: ${callbackError.message}`);
         }
@@ -924,14 +976,14 @@ export class IModelDb extends IModel {
             throw new IModelError(IModelStatus.BadRequest, "InMemory transform strategy requires cachedData to be provided.");
         }
         try {
-            if (callback?.postSchemaImportCallback)
-                await callback.postSchemaImportCallback(context);
-            if (this.isBriefcaseDb() && IModelHost.useSemanticRebase) {
-                this.saveChanges("Save changes from schema import post callback");
-            }
+            const postSchemaImportCallback = callback?.postSchemaImportCallback;
+            if (postSchemaImportCallback)
+                await postSchemaImportCallback(context);
+            if (this.isBriefcaseDb() && IModelHost.useSemanticRebase)
+                this.saveSchemaChanges("Save changes from schema import post callback");
         }
         catch (callbackError) {
-            this.abandonChanges();
+            this.abandonSchemaChanges();
             throw new IModelError(callbackError.errorNumber ?? IModelStatus.BadRequest, `Failed to execute postSchemaImportCallback: ${callbackError.message}`);
         }
         finally {
@@ -960,15 +1012,15 @@ export class IModelDb extends IModel {
             }
         }
         if (options?.channelUpgrade) {
+            const channelUpgrade = options.channelUpgrade;
             try {
-                await this.channels.upgradeChannel(options.channelUpgrade, this, options.data);
+                await this.channels.upgradeChannel(channelUpgrade, this, options.data);
                 // If semantic rebase is enabled and channel upgrade made changes, save them
-                if (this.isBriefcaseDb() && IModelHost.useSemanticRebase) {
-                    this.saveChanges();
-                }
+                if (this.isBriefcaseDb() && IModelHost.useSemanticRebase)
+                    this.saveSchemaChanges();
             }
             catch (error) {
-                this.abandonChanges();
+                this.abandonSchemaChanges();
                 throw error;
             }
         }
@@ -979,13 +1031,13 @@ export class IModelDb extends IModel {
         if (this[_nativeDb].schemaSyncEnabled()) {
             await SchemaSync.withLockedAccess(this, { openMode: OpenMode.Readonly, operationName: "schema sync" }, async (syncAccess) => {
                 const schemaSyncDbUri = syncAccess.getUri();
-                this.saveChanges();
+                this.saveSchemaChanges();
                 try {
                     nativeImportOp(schemas, { schemaLockHeld: false, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
                 }
                 catch (outerErr) {
                     if (DbResult.BE_SQLITE_ERROR_DataTransformRequired === outerErr.errorNumber) {
-                        this.abandonChanges();
+                        this.abandonSchemaChanges();
                         if (this[_nativeDb].getITwinId() !== Guid.empty)
                             await this.acquireSchemaLock();
                         try {
@@ -1038,13 +1090,16 @@ export class IModelDb extends IModel {
         if (options?.schemaImportCallbacks?.postSchemaImportCallback)
             await this.postSchemaImportCallback(options.schemaImportCallbacks, { iModel: this, resources: preSchemaImportCallbackResult, data: options.data });
     }
-    /** Import an ECSchema. On success, the schema definition is stored in the iModel.
+    /** Import ECSchema(s). On success, the schema definition is stored in the iModel.
      * This method is asynchronous (must be awaited) because, in the case where this IModelDb is a briefcase, this method first obtains the schema lock from the iModel server.
      * You must import a schema into an iModel before you can insert instances of the classes in that schema. See [[Element]]
-     * @param schemaFileName  array of Full paths to ECSchema.xml files to be imported.
+     * @param schemaFileNames  Files containing serialized ECSchemas.
      * @param {SchemaImportOptions} options - options during schema import.
      * @throws [[IModelError]] if the schema lock cannot be obtained or there is a problem importing the schema.
      * @note Changes are saved if importSchemas is successful and abandoned if not successful.
+     * @note To turn on native logging, use NativeLoggerCategory and a console appender.
+     * - For metadata differences between existing and imported schemas, turn on "ECDb" category.
+     * - For import details, turn on "SchemaImport" category.
      * - You can use NativeLoggerCategory to turn on the native logs. You can also control [what exactly is logged by the loggers](https://www.itwinjs.org/learning/common/logging/#controlling-what-is-logged).
      * - See [Schema Versioning]($docs/bis/guide/schema-evolution/schema-versioning-and-generations.md) for more information on acceptable changes to schemas.
      * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {RebaseHandler.recompute}.
@@ -1206,7 +1261,7 @@ export class IModelDb extends IModel {
         return this._jsClassMap;
     }
     /**
-     * Allows locally registering a schema for this imodel, in constrast to [Schemas.registerSchema] which is a global operation
+     * Allows locally registering a schema for this imodel, in contrast to [Schemas.registerSchema] which is a global operation
      */
     get schemaMap() {
         if (this._schemaMap === undefined)
@@ -1518,26 +1573,18 @@ export class IModelDb extends 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 Use EditTxn.saveFileProperty instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     saveFileProperty(prop, strValue, blobVal) {
-        if (this.isBriefcaseDb()) {
-            if (this.txns.isIndirectChanges) {
-                throw new IModelError(IModelStatus.BadRequest, "Cannot save file property while in an indirect change scope");
-            }
-        }
-        this[_nativeDb].saveFileProperty(prop, strValue, blobVal);
+        this[_implicitTxn].saveFileProperty(prop, strValue, blobVal);
     }
     /** 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 Use EditTxn.deleteFileProperty instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     deleteFileProperty(prop) {
-        if (this.isBriefcaseDb()) {
-            if (this.txns.isIndirectChanges) {
-                throw new IModelError(IModelStatus.BadRequest, "Cannot delete file property while in an indirect change scope");
-            }
-        }
-        this[_nativeDb].saveFileProperty(prop, undefined, undefined);
+        this[_implicitTxn].deleteFileProperty(prop);
     }
     /** Query for the next available major id for a "file property" from this iModel.
      * @param prop the FilePropertyProps that describes the property
@@ -1741,28 +1788,17 @@ export class IModelDb extends IModel {
      * @param name The name for the SettingDictionary. If a dictionary by that name already exists in the iModel, its value is replaced.
      * @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.
-     * @beta
+     * @beta @deprecated Use EditTxn.saveSettingDictionary instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     saveSettingDictionary(name, dict) {
-        this.withSqliteStatement("REPLACE INTO be_Prop(id,SubId,TxnMode,Namespace,Name,strData) VALUES(0,0,0,?,?,?)", (stmt) => {
-            stmt.bindString(1, IModelDb._settingPropNamespace);
-            stmt.bindString(2, name);
-            stmt.bindString(3, JSON.stringify(dict));
-            stmt.stepForWrite();
-        });
-        this.saveChanges("add settings");
+        this[_implicitTxn].saveSettingDictionary(name, dict);
     }
     /** Delete a SettingDictionary, previously added with [[saveSettingDictionary]], from this iModel.
      * @param name The name of the dictionary to delete.
-     * @beta
+     * @beta @deprecated Use EditTxn.deleteSettingDictionary instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
      */
     deleteSettingDictionary(name) {
-        this.withSqliteStatement("DELETE FROM be_Prop WHERE Namespace=? AND Name=?", (stmt) => {
-            stmt.bindString(1, IModelDb._settingPropNamespace);
-            stmt.bindString(2, name);
-            stmt.stepForWrite();
-        });
-        this.saveChanges("delete settings");
+        this[_implicitTxn].deleteSettingDictionary(name);
     }
     /** Load all setting dictionaries in this iModel into `this.workspace.settings` */
     loadIModelSettings() {
@@ -2037,33 +2073,19 @@ function processSchemaWriteStatus(status) {
         /** Insert a new model.
          * @param props The data for the new model.
          * @returns The newly inserted model's Id.
-         * @throws [[IModelError]] if unable to insert the model.
+         * @throws [[IModelError]] if insertion fails.
+         * @deprecated Use EditTxn.insertModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertModel(props) {
-            try {
-                return props.id = this._iModel[_nativeDb].insertModel(props);
-            }
-            catch (err) {
-                const error = new IModelError(err.errorNumber, `Error inserting model [${err.message}], class=${props.classFullName}`);
-                error.cause = err;
-                throw error;
-            }
+            return this._iModel[_implicitTxn].insertModel(props);
         }
         /** Update an existing model.
          * @param props the properties of the model to change
-         * @throws [[IModelError]] if unable to update the model.
+         * @throws [[IModelError]] if update fails.
+         * @deprecated Use EditTxn.updateModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateModel(props) {
-            try {
-                if (props.id)
-                    this[_cache].delete(props.id);
-                this._iModel[_nativeDb].updateModel(props);
-            }
-            catch (err) {
-                const error = new IModelError(err.errorNumber, `Error updating model [${err.message}], id: ${props.id}`);
-                error.cause = err;
-                throw error;
-            }
+            this._iModel[_implicitTxn].updateModel(props);
         }
         /** Mark the geometry of [[GeometricModel]] as having changed, by recording an indirect change to its GeometryGuid property.
          * Typically the GeometryGuid changes automatically when [[GeometricElement]]s within the model are modified, but
@@ -2071,32 +2093,20 @@ function processSchemaWriteStatus(status) {
          * [[GeometricElement]]s that reference those definition elements in their geometry streams.
          * 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 unable to update the geometry guid.
+         * @throws [[IModelError]] if the update fails.
+         * @deprecated 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) {
-            this._iModel.models[_cache].delete(modelId);
-            const error = this._iModel[_nativeDb].updateModelGeometryGuid(modelId);
-            if (error !== IModelStatus.Success)
-                throw new IModelError(error, `Error updating geometry guid for model ${modelId}`);
+            this._iModel[_implicitTxn].updateGeometryGuid(modelId);
         }
         /** Delete one or more existing models.
          * @param ids The Ids of the models to be deleted
-         * @throws [[IModelError]]
+         * @throws [[IModelError]] if deletion fails.
+         * @deprecated Use EditTxn.deleteModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteModel(ids) {
-            Id64.toIdSet(ids).forEach((id) => {
-                try {
-                    this[_cache].delete(id);
-                    this[_instanceKeyCache].deleteById(id);
-                    this._iModel[_nativeDb].deleteModel(id);
-                }
-                catch (err) {
-                    const error = new IModelError(err.errorNumber, `Error deleting model [${err.message}], id: ${id}`);
-                    error.cause = err;
-                    throw error;
-                }
-            });
+            this._iModel[_implicitTxn].deleteModel(ids);
         }
         /** For each specified [[GeometricModel]], attempts to obtain the union of the volumes of all geometric elements within that model.
          * @param ids The Id or Ids of the [[GeometricModel]]s for which to obtain the extents.
@@ -2314,26 +2324,15 @@ function processSchemaWriteStatus(status) {
         /** Insert a new element into the iModel.
          * @param elProps The properties of the new element.
          * @returns The newly inserted element's Id.
-         * @throws [[ITwinError]] if unable to insert the element.
+         * @throws [[ITwinError]] if insertion fails.
          * @note For convenience, the value of `elProps.id` is updated to reflect the resultant element's id.
          * 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 Use EditTxn.insertElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertElement(elProps, options) {
-            try {
-                this[_cache].delete({
-                    id: elProps.id,
-                    federationGuid: elProps.federationGuid,
-                    code: elProps.code,
-                });
-                return elProps.id = this._iModel[_nativeDb].insertElement(elProps, options);
-            }
-            catch (err) {
-                err.message = `Error inserting element [${err.message}]`;
-                err.metadata = { elProps };
-                throw err;
-            }
+            return this._iModel[_implicitTxn].insertElement(elProps, options);
         }
         /**
          * Update some properties of an existing element.
@@ -2344,126 +2343,33 @@ function processSchemaWriteStatus(status) {
          * @param elProps the properties of the element to update.
          * @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 unable to update the element.
+         * @throws [[ITwinError]] if update fails.
+         * @deprecated Use EditTxn.updateElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateElement(elProps) {
-            try {
-                if (elProps.id) {
-                    this[_instanceKeyCache].deleteById(elProps.id);
-                }
-                else {
-                    this[_instanceKeyCache].delete({
-                        federationGuid: elProps.federationGuid,
-                        code: elProps.code,
-                    });
-                }
-                this[_cache].delete({
-                    id: elProps.id,
-                    federationGuid: elProps.federationGuid,
-                    code: elProps.code,
-                });
-                this._iModel[_nativeDb].updateElement(elProps);
-            }
-            catch (err) {
-                err.message = `Error updating element [${err.message}], id: ${elProps.id}`;
-                err.metadata = { elProps };
-                throw err;
-            }
+            this._iModel[_implicitTxn].updateElement(elProps);
         }
         /** Delete one or more elements from this iModel.
          * @param ids The set of Ids of the element(s) to be deleted
          * @throws [[ITwinError]]
          * @see deleteDefinitionElements
+         * @deprecated Use EditTxn.deleteElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteElement(ids) {
-            const iModel = this._iModel;
-            Id64.toIdSet(ids).forEach((id) => {
-                try {
-                    this[_cache].delete({ id });
-                    this[_instanceKeyCache].deleteById(id);
-                    iModel[_nativeDb].deleteElement(id);
-                }
-                catch (err) {
-                    err.message = `Error deleting element [${err.message}], id: ${id}`;
-                    err.metadata = { elementId: id };
-                    throw err;
-                }
-            });
+            this._iModel[_implicitTxn].deleteElement(ids);
         }
         /** 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.
          * This method performs those expensive checks and then calls *delete* if not referenced.
-         * @param ids The Ids of the DefinitionElements to attempt to delete. To prevent multiple passes over the same GeometricElements, it is best to pass in the entire array of
+         * @param definitionElementIds The Ids of the DefinitionElements to attempt to delete. To prevent multiple passes over the same GeometricElements, it is best to pass in the entire array of
          * 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
-         * @beta
+         * @deprecated Use EditTxn.deleteDefinitionElements instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteDefinitionElements(definitionElementIds) {
-            const usageInfo = this._iModel[_nativeDb].queryDefinitionElementUsage(definitionElementIds);
-            if (!usageInfo) {
-                throw new IModelError(IModelStatus.BadRequest, "Error querying for DefinitionElement usage");
-            }
-            const usedIdSet = usageInfo.usedIds ? Id64.toIdSet(usageInfo.usedIds) : new Set();
-            const deleteIfUnused = (ids, used) => {
-                if (ids) {
-                    ids.forEach((id) => {
-                        if (!used.has(id))
-                            this._iModel.elements.deleteElement(id);
-                    });
-                }
-            };
-            try {
-                this._iModel[_nativeDb].beginPurgeOperation();
-                deleteIfUnused(usageInfo.spatialCategoryIds, usedIdSet);
-                deleteIfUnused(usageInfo.drawingCategoryIds, usedIdSet);
-                deleteIfUnused(usageInfo.viewDefinitionIds, usedIdSet);
-                deleteIfUnused(usageInfo.geometryPartIds, usedIdSet);
-                deleteIfUnused(usageInfo.lineStyleIds, usedIdSet);
-                deleteIfUnused(usageInfo.renderMaterialIds, usedIdSet);
-                deleteIfUnused(usageInfo.subCategoryIds, usedIdSet);
-                deleteIfUnused(usageInfo.textureIds, usedIdSet);
-                deleteIfUnused(usageInfo.displayStyleIds, usedIdSet);
-                deleteIfUnused(usageInfo.categorySelectorIds, usedIdSet);
-                deleteIfUnused(usageInfo.modelSelectorIds, usedIdSet);
-                if (usageInfo.otherDefinitionElementIds) {
-                    this._iModel.elements.deleteElement(usageInfo.otherDefinitionElementIds);
-                }
-            }
-            finally {
-                this._iModel[_nativeDb].endPurgeOperation();
-            }
-            if (usageInfo.viewDefinitionIds) {
-                // take another pass in case a deleted ViewDefinition was the only usage of these view-related DefinitionElements
-                let viewRelatedIds = [];
-                if (usageInfo.displayStyleIds)
-                    viewRelatedIds = viewRelatedIds.concat(usageInfo.displayStyleIds.filter((id) => usedIdSet.has(id)));
-                if (usageInfo.categorySelectorIds)
-                    viewRelatedIds = viewRelatedIds.concat(usageInfo.categorySelectorIds.filter((id) => usedIdSet.has(id)));
-                if (usageInfo.modelSelectorIds)
-                    viewRelatedIds = viewRelatedIds.concat(usageInfo.modelSelectorIds.filter((id) => usedIdSet.has(id)));
-                if (viewRelatedIds.length > 0) {
-                    const viewRelatedUsageInfo = this._iModel[_nativeDb].queryDefinitionElementUsage(viewRelatedIds);
-                    if (viewRelatedUsageInfo) {
-                        const usedViewRelatedIdSet = viewRelatedUsageInfo.usedIds ? Id64.toIdSet(viewRelatedUsageInfo.usedIds) : new Set();
-                        try {
-                            this._iModel[_nativeDb].beginPurgeOperation();
-                            deleteIfUnused(viewRelatedUsageInfo.displayStyleIds, usedViewRelatedIdSet);
-                            deleteIfUnused(viewRelatedUsageInfo.categorySelectorIds, usedViewRelatedIdSet);
-                            deleteIfUnused(viewRelatedUsageInfo.modelSelectorIds, usedViewRelatedIdSet);
-                        }
-                        finally {
-                            this._iModel[_nativeDb].endPurgeOperation();
-                        }
-                        viewRelatedIds.forEach((id) => {
-                            if (!usedViewRelatedIdSet.has(id))
-                                usedIdSet.delete(id);
-                        });
-                    }
-                }
-            }
-            return usedIdSet;
+            return this._iModel[_implicitTxn].deleteDefinitionElements(definitionElementIds);
         }
         /** Query for the child elements of the specified element.
          * @returns Returns an array of child element identifiers.
@@ -2654,47 +2560,26 @@ 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 Use EditTxn.insertAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertAspect(aspectProps) {
-            try {
-                return this._iModel[_nativeDb].insertElementAspect(aspectProps);
-            }
-            catch (err) {
-                const error = new IModelError(err.errorNumber, `Error inserting ElementAspect [${err.message}], class: ${aspectProps.classFullName}`, aspectProps);
-                error.cause = err;
-                throw error;
-            }
+            return this._iModel[_implicitTxn].insertAspect(aspectProps);
         }
         /** 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 Use EditTxn.updateAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateAspect(aspectProps) {
-            try {
-                this._iModel[_nativeDb].updateElementAspect(aspectProps);
-            }
-            catch (err) {
-                const error = new IModelError(err.errorNumber, `Error updating ElementAspect [${err.message}], id: ${aspectProps.id}`, aspectProps);
-                error.cause = err;
-                throw error;
-            }
+            this._iModel[_implicitTxn].updateAspect(aspectProps);
         }
         /** 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 Use EditTxn.deleteAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteAspect(aspectInstanceIds) {
-            const iModel = this._iModel;
-            Id64.toIdSet(aspectInstanceIds).forEach((aspectInstanceId) => {
-                try {
-                    iModel[_nativeDb].deleteElementAspect(aspectInstanceId);
-                }
-                catch (err) {
-                    const error = new IModelError(err.errorNumber, `Error deleting ElementAspect [${err.message}], id: ${aspectInstanceId}`);
-                    error.cause = err;
-                    throw error;
-                }
-            });
+            this._iModel[_implicitTxn].deleteAspect(aspectInstanceIds);
         }
     }
     IModelDb.Elements = Elements;
@@ -2737,11 +2622,11 @@ function processSchemaWriteStatus(status) {
             this._viewStore.container.accessToken = accessToken;
             return this._viewStore;
         }
-        /** @beta */
+        /**
+         * @beta @deprecated Use EditTxn.saveDefaultViewStore instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         */
         saveDefaultViewStore(arg) {
-            const props = { baseUri: arg.baseUri, containerId: arg.containerId, storageType: arg.storageType }; // sanitize to only known properties
-            this._iModel.saveFileProperty(Views.viewStoreProperty, JSON.stringify(props));
-            this._iModel.saveChanges("update default ViewStore");
+            this._iModel[_implicitTxn].saveDefaultViewStore(arg);
         }
         /** Query for the array of ViewDefinitionProps of the specified class and matching the specified IsPrivate setting.
          * @param className Query for view definitions of this class.
@@ -2884,7 +2769,7 @@ function processSchemaWriteStatus(status) {
             blob32[0] = Id64.getLowerUint32(viewId);
             blob32[1] = Id64.getUpperUint32(viewId);
             const blob8 = new Uint8Array(blob32.buffer);
-            this._iModel.saveFileProperty(spec, undefined, blob8);
+            this._iModel[_implicitTxn].saveFileProperty(spec, undefined, blob8);
         }
     }
     IModelDb.Views = Views;
@@ -3088,7 +2973,7 @@ export class BriefcaseDb extends IModelDb {
                 executeUpgrade();
                 await withBriefcaseDb(briefcase, async (db) => {
                     db[_nativeDb].schemaSyncPush(schemaSyncDbUri);
-                    db.saveChanges();
+                    db[_nativeDb].saveChanges();
                 });
                 syncAccess.synchronizeWithCloud();
             });
@@ -3453,7 +3338,7 @@ export class BriefcaseDb extends IModelDb {
         }
         try {
             await BriefcaseManager.revertTimelineChanges(this, arg);
-            this.saveChanges("Revert changes");
+            this[_nativeDb].saveChanges("Revert changes");
             if (!arg.description) {
                 arg.description = `Reverted changes from ${this.changeset.index} to ${arg.toIndex}${arg.skipSchemaChanges ? " (schema changes skipped)" : ""}`;
             }
@@ -3476,7 +3361,7 @@ export class BriefcaseDb extends IModelDb {
             }
         }
         finally {
-            this.abandonChanges();
+            this[_nativeDb].abandonChanges();
         }
     }
     /**
@@ -3506,7 +3391,7 @@ export class BriefcaseDb extends IModelDb {
     }
     close(options) {
         if (this.isBriefcase && this.isOpen && !this.isReadonly && this.txns.rebaser.inProgress()) {
-            this.abandonChanges();
+            this[_nativeDb].abandonChanges();
         }
         super.close(options);
         this.onClosed.raiseEvent();
@@ -3723,7 +3608,7 @@ export class SnapshotDb extends IModelDb {
                 throw new IModelError(IModelStatus.SQLiteError, "Error creating class views");
             }
             else {
-                this.saveChanges();
+                this[_nativeDb].saveChanges();
             }
         }
     }
@@ -3753,15 +3638,16 @@ export class StandaloneDb extends BriefcaseDb {
     }
     /**
      * @internal
-     * Called during close of the iModel. It will delete any pending txns, analyze and vacuum the iModel.
+     * Called during close of the StandaloneDb. It will delete any pending txns.
     */
     beforeClose() {
         super.beforeClose();
-        if (!this.isReadonly && this.txns.hasLocalChanges) {
-            this.saveChanges();
-            this.txns.deleteAllTxns();
-            this.saveChanges();
-        }
+        if (this.isReadonly || !this.txns.hasLocalChanges)
+            return;
+        const nativeDb = this[_nativeDb];
+        nativeDb.saveChanges();
+        nativeDb.deleteAllTxns();
+        nativeDb.saveChanges();
     }
     static tryFindByKey(key) {
         const db = super.tryFindByKey(key);
@@ -3817,7 +3703,7 @@ export class StandaloneDb extends BriefcaseDb {
         if (BentleyStatus.SUCCESS !== result)
             throw new IModelError(result, "Error creating class views");
         else
-            this.saveChanges();
+            this[_nativeDb].saveChanges();
     }
     /** Open a standalone iModel file.
      * @param filePath The path of the standalone iModel file.