@itwin/core-backend 5.14.0-dev.3 → 5.14.0-dev.4

package/lib/cjs/SchemaSync.d.ts

@@ -1,8 +1,9 @@
 import { CloudSqlite } from "./CloudSqlite";
 import { SQLiteDb, VersionedSqliteDb } from "./SQLiteDb";
-import { IModelDb } from "./IModelDb";
+import { BriefcaseDb, IModelDb } from "./IModelDb";
 import { GuidString, Id64String, OpenMode } from "@itwin/core-bentley";
 import { Code, LocalFileName } from "@itwin/core-common";
+import type { BlobContainer } from "./BlobContainerService";
 /** @internal */
 export declare namespace SchemaSync {
     /** Identifies an element to be reserved in a `SchemaSyncDb`. @internal */
@@ -21,13 +22,13 @@ export declare namespace SchemaSync {
         findReservedElement(federationGuid: GuidString): ReservedElement | undefined;
     }
     interface WriteMethods {
-        /** Reserve the specified elements in the `SchemaSyncDb`.  Throws if any of the requested reservations conflict with existing reservations. */
+        /** Reserve the specified elements in the `SchemaSyncDb`. Throws if any requested reservation conflicts with an existing reservation. */
         reserveElements(identities: ProposedElementReservation[]): Promise<void>;
     }
     /** A CloudSqlite database for synchronizing schema changes across briefcases.  */
     class SchemaSyncDb extends VersionedSqliteDb implements ReadMethods, WriteMethods {
         private _supportsReservations?;
-        readonly myVersion = "4.1.0";
+        readonly myVersion = "5.0.0";
         protected createDDL(): void;
         openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams, container?: CloudSqlite.CloudContainer): void;
         private ensureReservedElementsTable;
@@ -38,28 +39,133 @@ export declare namespace SchemaSync {
         private getNextReservedElementLocalId;
         private setNextReservedElementLocalId;
     }
-    const setTestCache: (iModel: IModelDb, cacheName?: string) => void;
-    const getCloudAccess: (arg: IModelDb | {
+    /** The `containerType` recorded on a BlobContainer that holds an iModel's `SchemaSyncDb`. */
+    const containerType = "schema-sync";
+    function setTestCache(iModel: IModelDb, cacheName?: string): void;
+    /** Either an open iModel or the name of a closed briefcase file. Every local read below accepts both, so
+     * a caller that has only a file name does not have to open a `BriefcaseDb` to ask a question about it.
+     */
+    type IModelOrFileName = IModelDb | {
         readonly fileName: LocalFileName;
-    }) => Promise<CloudAccess>;
-    const withLockedAccess: (iModel: IModelDb | {
-        readonly fileName: LocalFileName;
-    }, args: {
+    };
+    /** 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: IModelOrFileName): boolean;
+    /** 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: IModelOrFileName): CloudSqlite.ContainerProps | undefined;
+    function getCloudAccess(arg: IModelOrFileName): Promise<CloudAccess>;
+    /** Release an access obtained through [[getCloudAccess]]. */
+    function releaseCloudAccess(access: CloudAccess): void;
+    /** Arguments for [[withLockedAccess]]. */
+    interface WithLockedAccessArgs {
         operationName: string;
         openMode?: OpenMode;
         user?: string;
-    }, operation: (access: CloudAccess) => Promise<void>) => Promise<void>;
-    const withReadonlyAccess: (iModel: IModelDb | {
-        readonly fileName: LocalFileName;
-    }, operation: (access: CloudAccess) => Promise<void>) => Promise<void>;
-    const isEnabled: (iModel: IModelDb) => boolean;
-    /** Synchronize local briefcase schemas with cloud container */
-    const pull: (iModel: IModelDb) => Promise<void>;
-    const initializeForIModel: (arg: {
+    }
+    function withLockedAccess(iModel: IModelOrFileName, args: WithLockedAccessArgs, operation: (access: CloudAccess) => Promise<void>): Promise<void>;
+    /** 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: IModelDb): void;
+    /** 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: unknown): boolean;
+    /** Arguments for [[createContainerForIModel]]. */
+    interface CreateContainerForIModelArgs {
+        iModel: IModelDb;
+        label?: string;
+        description?: string;
+    }
+    /** 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.
+     */
+    function createContainerForIModel(arg: CreateContainerForIModelArgs): Promise<CloudSqlite.ContainerProps>;
+    /** Arguments for [[initializeForIModel]]. */
+    interface InitializeForIModelArgs {
         iModel: IModelDb;
         containerProps: CloudSqlite.ContainerProps;
+        /** Replace the container already recorded on this iModel instead of failing. */
         overrideContainer?: boolean;
-    }) => Promise<void>;
+    }
+    /** 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.
+     */
+    function initializeForIModel(arg: InitializeForIModelArgs): Promise<void>;
+    /** The part of a SchemaSyncDb to restore from an authoritative briefcase. @alpha */
+    type RepairScope = "schemaMetadata" | "schemaMetadataAndProfile";
+    /** Arguments for [[repairForIModel]]. @alpha */
+    interface RepairForIModelArgs {
+        /** A clean SchemaSync-enabled briefcase at the tip of the iModel timeline. */
+        iModel: BriefcaseDb;
+        /** Include the schema-owned EC and BeSQLite profile table definitions. */
+        scope?: RepairScope;
+    }
+    /** 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
+     */
+    function repairForIModel(arg: RepairForIModelArgs): Promise<void>;
+    /** Arguments for [[enableForIModel]]. */
+    interface EnableForIModelArgs {
+        iModel: IModelDb;
+        /** An existing container to use. When omitted one is created for this iModel. */
+        containerProps?: CloudSqlite.ContainerProps;
+        /** Replace the container already recorded on this iModel instead of failing. */
+        overrideContainer?: boolean;
+        label?: string;
+        description?: string;
+    }
+    /** 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.
+     */
+    function enableForIModel(arg: EnableForIModelArgs): Promise<CloudSqlite.ContainerProps>;
+    /** Arguments for [[CloudAccess.createNewContainer]]. */
+    interface CreateNewContainerProps {
+        scope: BlobContainer.Scope;
+        metadata: Omit<BlobContainer.Metadata, "containerType">;
+    }
     /** Provides access to a cloud-based `SchemaSyncDb` to hold ECSchemas.  */
     class CloudAccess extends CloudSqlite.DbAccess<SchemaSyncDb, ReadMethods, WriteMethods> {
         constructor(props: CloudSqlite.ContainerAccessProps);
@@ -70,6 +176,8 @@ export declare namespace SchemaSync {
        * @note this deletes any existing content in the container.
        */
         static initializeDb(props: CloudSqlite.ContainerProps): Promise<void>;
+        /** Create and initialize a new `schema-sync` BlobContainer to hold a `SchemaSyncDb`. */
+        static createNewContainer(args: CreateNewContainerProps): Promise<CloudSqlite.ContainerProps>;
     }
 }
 //# sourceMappingURL=SchemaSync.d.ts.map

package/lib/cjs/SchemaSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SchemaSync.d.ts","sourceRoot":"","sources":["../../src/SchemaSync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SchemaSync.d.ts","sourceRoot":"","sources":["../../src/SchemaSync.ts"],"names":[],"mappings":"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"}

package/lib/cjs/SchemaSync.js

@@ -19,14 +19,27 @@ 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 {
         _supportsReservations;
-        myVersion = "4.1.0";
+        myVersion = "5.0.0";
         createDDL() {
             this.ensureReservedElementsTable();
         }
@@ -138,116 +151,319 @@ var SchemaSync;
     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 sharedAccessByIModel = new Map();
-    SchemaSync.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 testSyncCache = nativeDb.queryLocalValue(testSyncCachePropKey);
-        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 {
-            // Reuse the existing access for this container so there is only ever one CloudAccess per container (per cache).
-            const sharedAccessKey = propsString + (testSyncCache ?? "");
-            const cached = sharedAccessByIModel.get(sharedAccessKey);
-            if (cached)
-                return cached;
-            const props = JSON.parse(propsString);
-            const accessToken = await CloudSqlite_1.CloudSqlite.requestToken(props);
-            const access = new CloudAccess({ ...props, accessToken });
-            Object.assign(access.lockParams, lockParams);
-            if (testSyncCache)
-                access.setCache(CloudSqlite_1.CloudSqlite.CloudCaches.getCache({ cacheName: testSyncCache }));
-            sharedAccessByIModel.set(sharedAccessKey, access);
-            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 SchemaSync.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) => {
+        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);
-        access.synchronizeWithCloud();
-        access.openForRead();
         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) {
@@ -264,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 = {}));