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

package/lib/esm/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/esm/SchemaSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SchemaSync.d.ts","sourceRoot":"","sources":["../../src/SchemaSync.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAe,QAAQ,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAkB,UAAU,EAAQ,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EAAoB,IAAI,EAA2D,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKpI,gBAAgB;AAChB,yBAAiB,UAAU,CAAC;IAM1B,0EAA0E;IAC1E,UAAiB,0BAA0B;QACzC,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC;QACpC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;QAC/B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;QACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;KAC/B;IAED,oFAAoF;IACpF,UAAiB,eAAgB,SAAQ,0BAA0B;QACjE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;KAChC;IAED,UAAiB,WAAW;QAC1B,iEAAiE;QACjE,mBAAmB,CAAC,cAAc,EAAE,UAAU,GAAG,eAAe,GAAG,SAAS,CAAC;KAC9E;IAED,UAAiB,YAAY;QAC3B,8IAA8I;QAC9I,eAAe,CAAC,UAAU,EAAE,0BAA0B,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC1E;IAED,kFAAkF;IAClF,MAAa,YAAa,SAAQ,iBAAkB,YAAW,WAAW,EAAE,YAAY;QACtF,OAAO,CAAC,qBAAqB,CAAC,CAAU;QACxC,SAAyB,SAAS,WAAW;kBAC1B,SAAS;QAIZ,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,cAAc;QAKvH,OAAO,CAAC,2BAA2B;QAmB5B,mBAAmB,CAAC,cAAc,EAAE,UAAU,GAAG,eAAe,GAAG,SAAS;QAyBnF,OAAO,CAAC,qBAAqB;QAkBhB,eAAe,CAAC,QAAQ,EAAE,0BAA0B,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;QAyCnF,OAAO,CAAC,eAAe;QAMvB,OAAO,CAAC,6BAA6B;QASrC,OAAO,CAAC,6BAA6B;KAGtC;IAMM,MAAM,YAAY,WAAY,QAAQ,cAAc,MAAM,SAKhE,CAAC;IAGK,MAAM,cAAc,QAAe,QAAQ,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,yBAmCxF,CAAC;IAEK,MAAM,gBAAgB,WAAkB,QAAQ,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,QAAQ;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,aAAa,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAOpO,CAAC;IAEK,MAAM,kBAAkB,WAAkB,QAAQ,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,aAAa,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CASjK,CAAC;IAEK,MAAM,SAAS,WAAY,QAAQ,YAEzC,CAAC;IAEF,+DAA+D;IACxD,MAAM,IAAI,WAAkB,QAAQ,kBAS1C,CAAC;IAEK,MAAM,mBAAmB,QAAe;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC;QAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;KAAE,kBA+B3I,CAAC;IAEF,0EAA0E;IAC1E,MAAa,WAAY,SAAQ,WAAW,CAAC,QAAQ,CAAC,YAAY,EAAE,WAAW,EAAE,YAAY,CAAC;oBACzE,KAAK,EAAE,WAAW,CAAC,oBAAoB;QAInD,MAAM;QAGb;;;;SAIC;eACmB,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,cAAc;KAGnE;CACF"}
+{"version":3,"file":"SchemaSync.d.ts","sourceRoot":"","sources":["../../src/SchemaSync.ts"],"names":[],"mappings":"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"}