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

package/lib/cjs/SchemaSync.js

@@ -8,6 +8,7 @@ exports.SchemaSync = void 0;
 /** @packageDocumentation
  * @module SQLiteDb
  */
+const semver = require("semver");
 const CloudSqlite_1 = require("./CloudSqlite");
 const SQLiteDb_1 = require("./SQLiteDb");
 const IModelDb_1 = require("./IModelDb");
@@ -18,117 +19,451 @@ const Symbols_1 = require("./internal/Symbols");
 /** @internal */
 var SchemaSync;
 (function (SchemaSync) {
-    const lockParams = { retryDelayMs: 1000, nRetries: 30 };
+    /** How long a briefcase waits for another briefcase's schema import to finish before giving up.
+     *
+     * `nRetries` alone does not bound the wait: when the count runs out `CloudSqlite.withLockedDb` asks
+     * `onFailure` what to do, and anything other than "stop" restarts the whole cycle. Without an
+     * `onFailure` the caller waits forever with no way to give up, so this supplies one.
+     */
+    const lockParams = {
+        retryDelayMs: 6000,
+        nRetries: 10,
+        onFailure: async (lockedBy, expires) => {
+            core_bentley_1.Logger.logInfo("SchemaSync", `schema sync container is held by ${lockedBy} until ${expires}; giving up`);
+            return "stop";
+        },
+    };
+    const reservedElementsTableName = "reserved_elements";
+    const maxLocalIdExclusive = 0x10000000000; // 2^40
+    const idSequenceProp = { namespace: "schemasync", name: "nextReservedElementLocalId" };
     /** A CloudSqlite database for synchronizing schema changes across briefcases.  */
     class SchemaSyncDb extends SQLiteDb_1.VersionedSqliteDb {
-        myVersion = "4.0.0";
-        createDDL() { }
+        _supportsReservations;
+        myVersion = "5.0.0";
+        createDDL() {
+            this.ensureReservedElementsTable();
+        }
+        openDb(dbName, openMode, container) {
+            super.openDb(dbName, openMode, container);
+            this._supportsReservations = semver.lte(this.myVersion, semver.minVersion(this.getRequiredVersions().readVersion) ?? "0.0.0");
+        }
+        ensureReservedElementsTable() {
+            if (this._supportsReservations)
+                return;
+            this.executeSQL(`
+        CREATE TABLE IF NOT EXISTS ${reservedElementsTableName} (
+          federationGuid BLOB    PRIMARY KEY,
+          elementId      INTEGER NOT NULL UNIQUE,
+          ecClassId      INTEGER NOT NULL,
+          codeSpecId     INTEGER NOT NULL,
+          codeScope      TEXT NOT NULL,
+          codeValue      TEXT COLLATE NOCASE
+        )`);
+            this.executeSQL(`CREATE UNIQUE INDEX IF NOT EXISTS idx_reserved_elem_code  ON ${reservedElementsTableName}(codeSpecId, codeScope, codeValue)`);
+            const minVersion = `^${this.myVersion}`;
+            this.setRequiredVersions({ readVersion: minVersion, writeVersion: minVersion });
+            this._supportsReservations = true;
+        }
+        findReservedElement(federationGuid) {
+            if (!this._supportsReservations)
+                return undefined;
+            return this.withPreparedSqliteStatement(`SELECT elementId, ecClassId, codeSpecId, codeScope, codeValue FROM ${reservedElementsTableName} WHERE federationGuid=?`, (stmt) => {
+                stmt.bindGuid(1, federationGuid);
+                if (!stmt.nextRow())
+                    return undefined;
+                return {
+                    federationGuid,
+                    elementId: stmt.getValueId(0),
+                    ecClassId: stmt.getValueId(1),
+                    code: new core_common_1.Code({
+                        spec: stmt.getValueId(2),
+                        scope: stmt.getValueString(3),
+                        value: stmt.getValueStringMaybe(4),
+                    }),
+                };
+            });
+        }
+        insertReservedElement(id, elementId) {
+            this.withPreparedSqliteStatement(`INSERT INTO ${reservedElementsTableName} (federationGuid, elementId, ecClassId, codeSpecId, codeScope, codeValue) VALUES (?, ?, ?, ?, ?, ?)`, (stmt) => {
+                stmt.bindGuid(1, id.federationGuid);
+                stmt.bindId(2, elementId);
+                stmt.bindId(3, id.ecClassId);
+                stmt.bindId(4, id.code.spec);
+                stmt.bindString(5, id.code.scope);
+                if (id.code.value === "")
+                    stmt.bindNull(6);
+                else
+                    stmt.bindString(6, id.code.value);
+                stmt.stepForWrite();
+            });
+        }
+        async reserveElements(elements) {
+            this.ensureReservedElementsTable();
+            // Insert new reservations as we go, so later entries in `elements` can dedupe against earlier ones
+            // through the shared (still-uncommitted) transaction. The caller commits on success and abandons on error.
+            let nextLocalId = this.getNextReservedElementLocalId();
+            const firstLocalId = nextLocalId;
+            for (const def of elements) {
+                if (!def.federationGuid || !core_bentley_1.Guid.isGuid(def.federationGuid)) {
+                    core_common_1.ElementReservationError.throwError("invalid-reservation", {
+                        message: "Element reservation requires an explicit, valid federationGuid",
+                    });
+                }
+                // Identity is always the federationGuid. If a reservation already exists for it, it must match exactly.
+                const existing = this.findReservedElement(def.federationGuid);
+                if (existing) {
+                    if (!this.existingMatches(existing, def)) {
+                        core_common_1.ElementReservationError.throwError("reservation-conflict", {
+                            message: `Element reservation conflict for federationGuid ${existing.federationGuid}: existing row does not match requested class/code`,
+                            federationGuid: existing.federationGuid,
+                        });
+                    }
+                    continue;
+                }
+                const elementId = core_bentley_1.Id64.fromLocalAndBriefcaseIds(nextLocalId, core_common_1.BriefcaseIdValue.SchemaSyncElementReserved);
+                this.insertReservedElement(def, elementId);
+                // skip a local id for each reserved category because category inserts always trigger a second insert for default subcategory
+                nextLocalId += def.isCategory ? 2 : 1;
+                if (nextLocalId >= maxLocalIdExclusive) {
+                    this.abandonChanges();
+                    core_common_1.ElementReservationError.throwError("id-sequence-exhausted", { message: `SchemaSync reserved-element local-id sequence exhausted` });
+                }
+            }
+            if (nextLocalId !== firstLocalId)
+                this.setNextReservedElementLocalId(nextLocalId);
+        }
+        existingMatches(existing, id) {
+            return existing.federationGuid === id.federationGuid
+                && existing.ecClassId === id.ecClassId
+                && existing.code.equals(id.code);
+        }
+        getNextReservedElementLocalId() {
+            const stored = this[Symbols_1._nativeDb].queryFileProperty(idSequenceProp, true);
+            const current = stored ? Number(stored) : 1;
+            if (!Number.isInteger(current) || current < 1)
+                core_common_1.ElementReservationError.throwError("corrupt-reservation-data", { message: `Corrupt SchemaSync reserved-element local-id counter: '${stored}'` });
+            return current;
+        }
+        setNextReservedElementLocalId(next) {
+            this[Symbols_1._nativeDb].saveFileProperty(idSequenceProp, String(next));
+        }
     }
     SchemaSync.SchemaSyncDb = SchemaSyncDb;
     const syncProperty = { namespace: "itwinjs", name: "SchemaSync" };
     const defaultDbName = "SchemaSyncDb";
+    /** The `containerType` recorded on a BlobContainer that holds an iModel's `SchemaSyncDb`. */
+    SchemaSync.containerType = "schema-sync";
     const testSyncCachePropKey = "test.schema_sync.cache_name";
     // for tests only
-    SchemaSync.setTestCache = (iModel, cacheName) => {
+    function setTestCache(iModel, cacheName) {
         if (cacheName)
             iModel[Symbols_1._nativeDb].saveLocalValue(testSyncCachePropKey, cacheName);
         else
             iModel[Symbols_1._nativeDb].deleteLocalValue(testSyncCachePropKey);
-    };
-    const getCloudAccess = async (arg) => {
-        let nativeDb;
-        const argIsIModelDb = arg instanceof IModelDb_1.IModelDb;
-        if (argIsIModelDb) {
-            nativeDb = arg[Symbols_1._nativeDb];
-        }
-        else {
-            nativeDb = new NativePlatform_1.IModelNative.platform.DgnDb();
-            nativeDb.openIModel(arg.fileName, core_bentley_1.OpenMode.Readonly);
-        }
-        const propsString = nativeDb.queryFileProperty(syncProperty, true);
-        if (!propsString)
-            throw new Error("iModel does not have a SchemaSyncDb");
+    }
+    SchemaSync.setTestCache = setTestCache;
+    /** Read from an open iModel, or from a closed file opened readonly for the duration of `operation`. */
+    function readFromIModel(arg, operation) {
+        if (arg instanceof IModelDb_1.IModelDb)
+            return operation(arg[Symbols_1._nativeDb]);
+        const nativeDb = new NativePlatform_1.IModelNative.platform.DgnDb();
+        nativeDb.openIModel(arg.fileName, core_bentley_1.OpenMode.Readonly);
         try {
-            const props = JSON.parse(propsString);
-            const accessToken = await CloudSqlite_1.CloudSqlite.requestToken(props);
-            const access = new CloudAccess({ ...props, accessToken });
-            Object.assign(access.lockParams, lockParams);
-            const testSyncCache = nativeDb.queryLocalValue(testSyncCachePropKey);
-            if (testSyncCache)
-                access.setCache(CloudSqlite_1.CloudSqlite.CloudCaches.getCache({ cacheName: testSyncCache }));
-            return access;
+            return operation(nativeDb);
         }
         finally {
-            if (!argIsIModelDb) {
-                nativeDb.closeFile();
+            nativeDb.closeFile();
+        }
+    }
+    /** Whether this iModel's ECSchemas are governed by a `SchemaSyncDb`.
+     *
+     * This is the single question every schema operation branches on. It reads one `be_Prop` row written when
+     * schema sync was enabled and carried to every other briefcase by that changeset - no cloud access, and it
+     * works on a readonly briefcase, a checkpoint, or a closed file.
+     * @note This says nothing about whether the container is reachable, or even named. Use
+     * [[queryContainerProps]] for that. The two are separate on purpose: a file that says it is governed by a
+     * sync db must never fall back to importing schemas on its own, whatever state the container is in.
+     */
+    function isEnabled(arg) {
+        return readFromIModel(arg, (nativeDb) => nativeDb.schemaSyncEnabled());
+    }
+    SchemaSync.isEnabled = isEnabled;
+    /** One pass over the values schema sync keeps in the file: which container holds the sync db, plus the
+     * test-only cache override. Read together so a closed file is opened once.
+     */
+    function readLocalSyncProps(arg) {
+        return readFromIModel(arg, (nativeDb) => {
+            const propsString = nativeDb.queryFileProperty(syncProperty, true);
+            let containerProps;
+            if (propsString !== undefined) {
+                try {
+                    containerProps = JSON.parse(propsString);
+                }
+                catch (e) {
+                    // Deliberately not swallowed into `undefined`: that would read as "schema sync was never
+                    // enabled" and let this briefcase import schemas on its own.
+                    throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_CORRUPT, `iModel names a SchemaSyncDb container but the property cannot be read: ${core_bentley_1.BentleyError.getErrorMessage(e)}`);
+                }
+            }
+            return {
+                containerProps,
+                testCacheName: nativeDb.queryLocalValue(testSyncCachePropKey),
+            };
+        });
+    }
+    /** The container holding this iModel's `SchemaSyncDb`, or `undefined` if schema sync was never enabled.
+     *
+     * Local read of the same `be_Prop` file property that [[initializeForIModel]] wrote. Requesting an access
+     * token for the container is a separate, asynchronous step.
+     */
+    function queryContainerProps(arg) {
+        return readLocalSyncProps(arg).containerProps;
+    }
+    SchemaSync.queryContainerProps = queryContainerProps;
+    const sharedAccessByContainer = new Map();
+    const sharedAccessByInstance = new WeakMap();
+    async function getCloudAccess(arg) {
+        const { containerProps, testCacheName } = readLocalSyncProps(arg);
+        if (undefined === containerProps)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_NOTFOUND, "iModel does not have a SchemaSyncDb");
+        const sharedAccessKey = JSON.stringify(containerProps) + (testCacheName ?? "");
+        let shared = sharedAccessByContainer.get(sharedAccessKey);
+        if (undefined === shared) {
+            const pending = (async () => {
+                const accessToken = await CloudSqlite_1.CloudSqlite.requestToken(containerProps);
+                const access = new CloudAccess({ ...containerProps, accessToken });
+                Object.assign(access.lockParams, lockParams);
+                if (testCacheName)
+                    access.setCache(CloudSqlite_1.CloudSqlite.CloudCaches.getCache({ cacheName: testCacheName }));
+                const created = { access, key: sharedAccessKey, referenceCount: 0 };
+                sharedAccessByInstance.set(access, created);
+                return created;
+            })();
+            sharedAccessByContainer.set(sharedAccessKey, pending);
+            try {
+                shared = await pending;
+                if (sharedAccessByContainer.get(sharedAccessKey) === pending)
+                    sharedAccessByContainer.set(sharedAccessKey, shared);
+            }
+            catch (error) {
+                if (sharedAccessByContainer.get(sharedAccessKey) === pending)
+                    sharedAccessByContainer.delete(sharedAccessKey);
+                throw error;
             }
         }
-    };
-    SchemaSync.withLockedAccess = async (iModel, args, operation) => {
-        const access = await getCloudAccess(iModel);
-        try {
-            await access.withLockedDb(args, async () => operation(access));
+        else if (shared instanceof Promise) {
+            shared = await shared;
         }
-        finally {
+        ++shared.referenceCount;
+        return shared.access;
+    }
+    SchemaSync.getCloudAccess = getCloudAccess;
+    /** Release an access obtained through [[getCloudAccess]]. */
+    function releaseCloudAccess(access) {
+        const shared = sharedAccessByInstance.get(access);
+        if (undefined === shared) {
             access.close();
+            return;
         }
-    };
-    SchemaSync.withReadonlyAccess = async (iModel, operation) => {
-        const access = await getCloudAccess(iModel);
-        access.synchronizeWithCloud();
-        access.openForRead();
+        if (--shared.referenceCount > 0)
+            return;
+        sharedAccessByInstance.delete(access);
+        if (sharedAccessByContainer.get(shared.key) === shared)
+            sharedAccessByContainer.delete(shared.key);
+        access.close();
+    }
+    SchemaSync.releaseCloudAccess = releaseCloudAccess;
+    async function withLockedAccess(iModel, args, operation) {
+        const access = await SchemaSync.getCloudAccess(iModel);
         try {
-            await operation(access);
+            await access.withLockedDb(args, async () => operation(access));
         }
         finally {
-            access.close();
+            releaseCloudAccess(access);
         }
-    };
-    SchemaSync.isEnabled = (iModel) => {
-        return iModel[Symbols_1._nativeDb].schemaSyncEnabled();
-    };
-    /** Synchronize local briefcase schemas with cloud container */
-    SchemaSync.pull = async (iModel) => {
-        if (iModel[Symbols_1._nativeDb].schemaSyncEnabled() && !iModel.isReadonly) {
-            await SchemaSync.withReadonlyAccess(iModel, async (syncAccess) => {
-                const schemaSyncDbUri = syncAccess.getUri();
-                iModel.clearCaches();
-                iModel[Symbols_1._nativeDb].schemaSyncPull(schemaSyncDbUri);
-                iModel[Symbols_1._implicitTxn].saveChanges("schema synchronized with cloud container");
-            });
+    }
+    SchemaSync.withLockedAccess = withLockedAccess;
+    /** Build the tables and indexes the briefcase's `ec_` rows describe. A merged schema changeset carries
+     * those rows but no DDL, so the physical columns are missing until this runs. Needs no cloud access.
+     */
+    function updateDbSchema(iModel) {
+        if (isEnabled(iModel) && !iModel.isReadonly) {
+            iModel.clearCaches();
+            iModel[Symbols_1._nativeDb].schemaSyncUpdateDbSchema();
+            iModel[Symbols_1._implicitTxn].saveChanges("materialized db schema from ec_ tables");
         }
-    };
-    SchemaSync.initializeForIModel = async (arg) => {
-        const props = { baseUri: arg.containerProps.baseUri, containerId: arg.containerProps.containerId, storageType: arg.containerProps.storageType }; // sanitize to only known properties
+    }
+    SchemaSync.updateDbSchema = updateDbSchema;
+    /** Whether a failed [[IModelDb.importSchemas]] can be retried through the upgrade path.
+     *
+     * The update tier refuses two kinds of change: one that has to move data between columns, and one
+     * that destroys instances or property values. They arrive as different statuses because they are
+     * different changes, but they mean one thing to a caller - this needs
+     * [[BriefcaseDb.upgradeSchemas]], which takes the exclusive schema lock.
+     *
+     * The retry is the app's decision, not the platform's: taking that lock disturbs everyone else, so
+     * only the app knows whether to do it now, schedule it, or tell the user.
+     * ```ts
+     * try {
+     *   await db.importSchemas(files);
+     * } catch (e) {
+     *   if (!SchemaSync.requiresUpgrade(e)) throw e;
+     *   await db.upgradeSchemas(files, { description: "..." });
+     * }
+     * ```
+     * @internal
+     */
+    function requiresUpgrade(error) {
+        const errorNumber = error?.errorNumber;
+        return errorNumber === core_bentley_1.DbResult.BE_SQLITE_ERROR_DataTransformRequired
+            || errorNumber === core_bentley_1.DbResult.BE_SQLITE_ERROR_DataDeletionRequired;
+    }
+    SchemaSync.requiresUpgrade = requiresUpgrade;
+    /** Create a cloud container to hold this iModel's `SchemaSyncDb`, and initialize it as empty.
+     *
+     * The container is scoped to the iModel, so the service deletes it when the iModel is deleted. Pass the
+     * returned props to [[initializeForIModel]] - the two calls together are what enables schema sync on an
+     * iModel that was created without it.
+     * @note The current user must be authorized to create containers for the iTwin.
+     */
+    async function createContainerForIModel(arg) {
         const iModel = arg.iModel;
+        const iTwinId = iModel.iTwinId;
+        if (undefined === iTwinId)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot create a SchemaSync container for an iModel that has no iTwin");
+        return CloudAccess.createNewContainer({
+            scope: { iTwinId, iModelId: iModel.iModelId },
+            metadata: { label: arg.label ?? `SchemaSync for ${iModel.name}`, description: arg.description },
+        });
+    }
+    SchemaSync.createContainerForIModel = createContainerForIModel;
+    /** Refuse initialization before a caller provisions a container, then hold the exclusive schema lock and pull to the tip. */
+    async function prepareToInitializeForIModel(iModel, overrideContainer) {
         const briefcase = iModel instanceof IModelDb_1.BriefcaseDb ? iModel : undefined;
+        if (briefcase && !briefcase.locks.isServerBased)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot enable SchemaSync without server-based locking");
+        if (briefcase && (iModel[Symbols_1._nativeDb].hasUnsavedChanges() || briefcase.txns.hasLocalChanges))
+            throw new core_common_1.IModelError(core_bentley_1.ChangeSetStatus.HasLocalChanges, "Cannot enable SchemaSync while there are local changes");
+        const assertContainerCanBeInitialized = () => {
+            const localInfo = iModel[Symbols_1._nativeDb].schemaSyncGetLocalDbInfo();
+            if (localInfo && !overrideContainer)
+                throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, `Local db already initialized to schema sync (container-id: ${localInfo.id})`);
+        };
+        assertContainerCanBeInitialized();
         await iModel.acquireSchemaLock();
-        if (briefcase) {
-            if (briefcase.txns.hasLocalChanges) {
-                throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Enabling SchemaSync for iModel failed. There are unsaved or un-pushed local changes.");
-            }
-            await briefcase.pullChanges();
-        }
+        await briefcase?.pullChanges();
+        assertContainerCanBeInitialized();
+        return briefcase;
+    }
+    async function initializeAfterPreflight(arg, briefcase) {
+        const props = { baseUri: arg.containerProps.baseUri, containerId: arg.containerProps.containerId, storageType: arg.containerProps.storageType }; // sanitize to only known properties
+        const iModel = arg.iModel;
+        const description = arg.overrideContainer
+            ? `Overriding SchemaSync for iModel with container-id: ${props.containerId}`
+            : `Enable SchemaSync for iModel with container-id: ${props.containerId}`;
+        const txnBeforeInit = briefcase?.txns.getCurrentTxnId();
         try {
             iModel[Symbols_1._implicitTxn].saveFileProperty(syncProperty, JSON.stringify(props));
-            await SchemaSync.withLockedAccess(arg.iModel, { operationName: "initialize schemaSync", openMode: core_bentley_1.OpenMode.Readonly }, async (syncAccess) => {
-                iModel[Symbols_1._nativeDb].schemaSyncInit(syncAccess.getUri(), props.containerId, arg.overrideContainer ?? false);
-                iModel[Symbols_1._implicitTxn].saveChanges(`Enable SchemaSync  (container id: ${props.containerId})`);
-            });
-        }
-        catch (err) {
-            throw err;
+            try {
+                await withLockedAccess(iModel, { operationName: "initialize schemaSync", openMode: core_bentley_1.OpenMode.Readonly }, async (syncAccess) => {
+                    iModel[Symbols_1._nativeDb].schemaSyncInit(syncAccess.getUri(), props.containerId, arg.overrideContainer ?? false);
+                    iModel[Symbols_1._implicitTxn].saveChanges(description);
+                });
+            }
+            catch (error) {
+                iModel[Symbols_1._implicitTxn].abandonChanges();
+                if (briefcase && txnBeforeInit !== undefined && briefcase.txns.getCurrentTxnId() !== txnBeforeInit) {
+                    const status = briefcase[Symbols_1._nativeDb].cancelTo(txnBeforeInit, true);
+                    if (status !== core_bentley_1.IModelStatus.Success)
+                        core_bentley_1.Logger.logError("SchemaSync", `Failed to roll back schema sync initialization after the container upload failed: ${core_bentley_1.IModelStatus[status] ?? status}`);
+                }
+                throw error;
+            }
+            // Upload the initialized container before publishing the property that tells every briefcase to use it.
+            // If the push fails, this briefcase keeps the local txn and exclusive schema lock so the push can be retried.
+            await briefcase?.pushChanges({ description });
         }
         finally {
             iModel[Symbols_1._implicitTxn].abandonChanges();
         }
-        if (briefcase) {
-            if (arg.overrideContainer)
-                await briefcase.pushChanges({ description: `Overriding SchemaSync for iModel with container-id: ${props.containerId}` });
-            else
-                await briefcase.pushChanges({ description: `Enable SchemaSync for iModel with container-id: ${props.containerId}` });
-        }
+        await iModel.initializeSharedElementReservations();
+    }
+    /** Enable schema sync for an iModel, seeding the container from this briefcase.
+     * @note Takes the exclusive schema lock, refuses local changes, and pulls the briefcase to the tip before writing the container.
+     * If this operation fails after acquiring the schema lock, it leaves the lock held.
+     */
+    async function initializeForIModel(arg) {
+        const briefcase = await prepareToInitializeForIModel(arg.iModel, arg.overrideContainer ?? false);
+        await initializeAfterPreflight(arg, briefcase);
+    }
+    SchemaSync.initializeForIModel = initializeForIModel;
+    const nativeRepairScope = {
+        schemaMetadata: 0,
+        schemaMetadataAndProfile: 1,
     };
+    /** Restore the schema-owned portion of the SchemaSyncDb from a briefcase at the tip of the timeline.
+     *
+     * This operation takes the exclusive schema lock and refuses to pull or modify the briefcase. Element
+     * reservations and all other target-only state in the SchemaSyncDb are preserved.
+     * @alpha
+     */
+    async function repairForIModel(arg) {
+        const iModel = arg.iModel;
+        if (!isEnabled(iModel))
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot repair SchemaSync because it is not enabled for this iModel");
+        if (iModel[Symbols_1._nativeDb].hasUnsavedChanges() || iModel.txns.hasLocalChanges)
+            throw new core_common_1.IModelError(core_bentley_1.ChangeSetStatus.HasLocalChanges, "Cannot repair SchemaSync while there are local changes");
+        if (!iModel.locks.isServerBased)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot repair SchemaSync without server-based locking");
+        if (arg.scope !== undefined && arg.scope !== "schemaMetadata" && arg.scope !== "schemaMetadataAndProfile")
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Unknown SchemaSync repair scope");
+        const briefcaseManagerModule = await Promise.resolve().then(() => require("./BriefcaseManager"));
+        const assertBriefcaseIsAtTip = async () => {
+            const latestChangeset = await briefcaseManagerModule.BriefcaseManager.getLatestChangeset({ iModelId: iModel.iModelId });
+            if (latestChangeset.id !== iModel.changeset.id)
+                throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot repair SchemaSync from a briefcase that is not at the tip of the iModel timeline");
+        };
+        // Avoid asking Hub for an exclusive lock it cannot grant to a briefcase that first needs to pull.
+        await assertBriefcaseIsAtTip();
+        const schemaLockWasHeld = iModel.holdsSchemaLock;
+        if (!schemaLockWasHeld)
+            await iModel.acquireSchemaLock();
+        try {
+            // Close the race between the preflight query and acquiring the exclusive lock.
+            await assertBriefcaseIsAtTip();
+            const repairScope = nativeRepairScope[arg.scope ?? "schemaMetadata"];
+            await withLockedAccess(iModel, { openMode: core_bentley_1.OpenMode.Readonly, operationName: "repair schema sync" }, async (syncAccess) => {
+                const nativeDb = iModel[Symbols_1._nativeDb];
+                nativeDb.schemaSyncRepair(syncAccess.getUri(), repairScope);
+            });
+            core_bentley_1.Logger.logInfo("SchemaSync", `Repaired SchemaSyncDb from changeset ${iModel.changeset.id || "0"}`);
+        }
+        finally {
+            if (!schemaLockWasHeld)
+                await iModel.locks.abandonAllLocks();
+        }
+    }
+    SchemaSync.repairForIModel = repairForIModel;
+    /** Turn schema sync on for an iModel: create the container if needed, record it, and seed it.
+     *
+     * The single call callers should use. [[createContainerForIModel]] and [[initializeForIModel]] have
+     * to happen in this order, and an iModel left between the two is one that names a container nothing
+     * has seeded.
+     * @returns the container props recorded on the iModel.
+     * @note Takes the exclusive schema lock and pushes, same protocol as [[BriefcaseDb.upgradeSchemas]] -
+     * every operation that changes how a file is governed uses it. If this operation fails after acquiring the schema lock,
+     * it leaves the lock held.
+     */
+    async function enableForIModel(arg) {
+        if (undefined === arg.containerProps && undefined === arg.iModel.iTwinId)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Cannot create a SchemaSync container for an iModel that has no iTwin");
+        const briefcase = await prepareToInitializeForIModel(arg.iModel, arg.overrideContainer ?? false);
+        const containerProps = arg.containerProps
+            ?? await createContainerForIModel({ iModel: arg.iModel, label: arg.label, description: arg.description });
+        await initializeAfterPreflight({ iModel: arg.iModel, containerProps, overrideContainer: arg.overrideContainer }, briefcase);
+        return containerProps;
+    }
+    SchemaSync.enableForIModel = enableForIModel;
     /** Provides access to a cloud-based `SchemaSyncDb` to hold ECSchemas.  */
     class CloudAccess extends CloudSqlite_1.CloudSqlite.DbAccess {
         constructor(props) {
@@ -145,6 +480,12 @@ var SchemaSync;
         static async initializeDb(props) {
             return super._initializeDb({ props, dbType: SchemaSyncDb, dbName: defaultDbName });
         }
+        /** Create and initialize a new `schema-sync` BlobContainer to hold a `SchemaSyncDb`. */
+        static async createNewContainer(args) {
+            const props = await this.createBlobContainer({ scope: args.scope, metadata: { ...args.metadata, containerType: SchemaSync.containerType } });
+            await this.initializeDb(props);
+            return props;
+        }
     }
     SchemaSync.CloudAccess = CloudAccess;
 })(SchemaSync || (exports.SchemaSync = SchemaSync = {}));