Add integrityCheck() function (backport #8958) [release/5.6.x] (#8986)

Co-authored-by: Michael Swiger <108895074+MichaelSwigerAtBentley@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: imodeljs-admin <38288322+imodeljs-admin@users.noreply.github.com>
Co-authored-by: anmolshres98 <anmolshres98@users.noreply.github.com>

Author: 5 people

.vscode/cSpell.json

@@ -234,6 +234,7 @@
     "Linestyle",
     "lineweight",
     "linework",
+    "Linktable",
     "listboxitem",
     "lstyle",
     "Manip",

common/api/core-backend.api.md

@@ -3721,6 +3721,8 @@ export abstract class IModelDb extends IModel {
     protected initializeIModelDb(when?: "pullMerge"): void;
     // @beta
     inlineGeometryParts(): InlineGeometryPartsResult;
+    // @beta
+    integrityCheck(options?: IntegrityCheckOptions): Promise<IntegrityCheckResult[]>;
     get isBriefcase(): boolean;
     isBriefcaseDb(): this is BriefcaseDb;
     // @internal
@@ -4284,6 +4286,23 @@ export interface InstanceChange {
     summaryId: Id64String;
 }
 
+// @beta
+export interface IntegrityCheckOptions {
+    quickCheck?: boolean;
+    specificChecks?: {
+        checkDataColumns?: boolean;
+        checkECProfile?: boolean;
+        checkNavigationClassIds?: boolean;
+        checkNavigationIds?: boolean;
+        checkLinktableForeignKeyClassIds?: boolean;
+        checkLinktableForeignKeyIds?: boolean;
+        checkClassIds?: boolean;
+        checkDataSchema?: boolean;
+        checkSchemaLoad?: boolean;
+        checkMissingChildRows?: boolean;
+    };
+}
+
 // @public
 export abstract class IpcHandler {
     abstract get channelName(): string;

common/api/summary/core-backend.exports.csv

@@ -360,6 +360,7 @@ internal;function;initializeTracing
 beta;interface;InlineGeometryPartsResult
 public;interface;InsertElementOptions
 beta;interface;InstanceChange
+beta;interface;IntegrityCheckOptions
 public;class;IpcHandler
 public;class;IpcHost
 public;interface;IpcHostOpts

common/changes/@itwin/core-backend/mike-fix-pragma_2026-02-02-17-58.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-backend",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-backend"
+}

common/changes/@itwin/core-backend/mike-fix-pragma_2026-02-06-16-41.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-backend",
+      "comment": "Add iModelDb.integrityCheck function that checks imodel database for corruption and reports results",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-backend"
+}

common/config/rush/pnpm-lock.yaml

@@ -113,7 +113,7 @@
     "webpack": "^5.97.1"
   },
   "dependencies": {
-    "@bentley/imodeljs-native": "5.6.14",
+    "@bentley/imodeljs-native": "5.6.15",
     "@itwin/object-storage-azure": "^3.0.4",
     "@azure/storage-blob": "^12.28.0",
     "form-data": "^4.0.4",

core/backend/package.json

@@ -73,6 +73,8 @@ import { ECVersion, SchemaContext, SchemaJsonLocater } from "@itwin/ecschema-met
 import { SchemaMap } from "./Schema";
 import { ElementLRUCache, InstanceKeyLRUCache } from "./internal/ElementLRUCache";
 import { IModelIncrementalSchemaLocater } from "./IModelIncrementalSchemaLocater";
+import { IntegrityCheckKey, IntegrityCheckResult, integrityCheckTypeMap, performQuickIntegrityCheck, performSpecificIntegrityCheck } from "./internal/IntegrityCheck";
+
 // spell:ignore fontid fontmap
 
 const loggerCategory: string = BackendLoggerCategory.IModelDb;
@@ -130,6 +132,38 @@ export interface ComputedProjectExtents {
   outliers?: Id64Array;
 }
 
+/**
+ * Options for performing integrity checks on an iModel.
+ * @beta
+ */
+export interface IntegrityCheckOptions {
+  /** If true, perform a quick integrity check that only reports whether each check passed or failed, without detailed results. */
+  quickCheck?: boolean;
+  /** Options for performing specific integrity checks with detailed results. */
+  specificChecks?: {
+    /** If true, checks if all the required columns exist in data tables. Issues are returned as a list of those tables/columns. */
+    checkDataColumns?: boolean;
+    /** If true, checks if the profile table, indexes, and triggers are present. Does not check be_* tables. Issues are returned as a list of tables/indexes/triggers which were not found or have different DDL. */
+    checkECProfile?: boolean;
+    /** If true, checks if RelClassId of a Navigation property is a valid ECClassId. It does not check the value to match the relationship class. */
+    checkNavigationClassIds?: boolean;
+    /** If true, checks if Id of a Navigation property matches a valid row primary class. */
+    checkNavigationIds?: boolean;
+    /** If true, checks if SourceECClassId or TargetECClassId of a link table matches a valid ECClassId. */
+    checkLinktableForeignKeyClassIds?: boolean;
+    /** If true, checks if SourceECInstanceId or TargetECInstanceId of a link table matches a valid row in primary class. */
+    checkLinktableForeignKeyIds?: boolean;
+    /** If true, checks persisted ECClassId in all data tables and makes sure they are valid. */
+    checkClassIds?: boolean;
+    /** If true, checks if all the required data tables and indexes exist for mapped classes. Issues are returned as a list of tables/columns which were not found or have different DDL. */
+    checkDataSchema?: boolean;
+    /** If true, checks if all schemas can be loaded into memory. */
+    checkSchemaLoad?: boolean;
+    /** If true, checks if all child rows have a corresponding parent row. */
+    checkMissingChildRows?: boolean;
+  }
+}
+
 /**
  * Options for the importing of schemas
  * @public
@@ -611,6 +645,60 @@ export abstract class IModelDb extends IModel {
     this[_nativeDb].analyze();
   }
 
+  /**
+   * Performs integrity checks on this iModel.
+   * Types of integrity checks that can be performed are:
+   *
+   * Default Check:
+   * - Quick Check: Runs all integrity checks below and returns whether each check passed or failed, without detailed results.
+   *
+   * Specific Checks:
+   * - Data Columns Check: Checks if all the required columns exist in data tables. Issues are returned as a list of those tables/columns.
+   * - EC Profile Check: Checks if the profile table, indexes, and triggers are present. Does not check be_* tables. Issues are returned as a list of tables/indexes/triggers which were not found or have different DDL.
+   * - Navigation Class Ids Check: Checks if RelClassId of a Navigation property is a valid ECClassId. It does not check the value to match the relationship class.
+   * - Navigation Ids Check: Checks if Id of a Navigation property matches a valid row primary class.
+   * - Linktable Foreign Key Class Ids Check: Checks if SourceECClassId or TargetECClassId of a link table matches a valid ECClassId.
+   * - Linktable Foreign Key Ids Check: Checks if SourceECInstanceId or TargetECInstanceId of a link table matches a valid row in primary class.
+   * - Class Ids Check: Checks persisted ECClassId in all data tables and makes sure they are valid.
+   * - Data Schema Check: Checks if all the required data tables and indexes exist for mapped classes. Issues are returned as a list of tables/columns which were not found or have different DDL.
+   * - Schema Load Check: Checks if all schemas can be loaded into memory.
+   * - Missing Child Rows Check: Checks if all child rows have a corresponding parent row.
+   *
+   * @param options Options specifying which integrity checks to perform. If no options are provided or all options are false, a quick check will be performed by default.
+   * @returns An array of integrity check results.
+   * @throws [[IModelError]] if the iModel is not open.
+   * @beta
+   */
+  public async integrityCheck(options?: IntegrityCheckOptions): Promise<IntegrityCheckResult[]> {
+    if (!this.isOpen)
+      throw new IModelError(IModelStatus.BadRequest, "IModel is not open");
+
+    // Default to quick check if no options provided at all, or if not explicitly set and no specific checks are enabled
+    if (!options || (!options.quickCheck && (!options.specificChecks || !Object.values(options.specificChecks).some(Boolean)))) {
+      options = { ...options, quickCheck: true };
+    }
+
+    const integrityCheckResults: IntegrityCheckResult[] = [];
+    // Perform a quick check if requested
+    if (options.quickCheck) {
+      const results = await performQuickIntegrityCheck(this);
+      const passed = results.every((result) => result.passed);
+      integrityCheckResults.push({ check: "Quick Check", passed, results });
+    }
+    // Perform all specific checks requested
+    if (options.specificChecks) {
+      for (const [checkKey, checkParams] of Object.entries(integrityCheckTypeMap)) {
+        if (options.specificChecks[checkKey as keyof typeof options.specificChecks]) {
+          const results = await performSpecificIntegrityCheck(this, checkKey as IntegrityCheckKey);
+          const passed = results.length === 0;
+          integrityCheckResults.push({ check: checkParams.name, passed, results });
+        }
+      }
+    }
+
+    return integrityCheckResults;
+  }
+
   /** @internal */
   public async refreshContainerForRpc(_userAccessToken: AccessToken): Promise<void> { }