@twin.org/entity-storage-connector-mysql 0.0.3-next.9 → 0.9.0-next.1

package/dist/es/models/IMySqlEntityStorageConnectorConstructorOptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"IMySqlEntityStorageConnectorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IMySqlEntityStorageConnectorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMySqlEntityStorageConnectorConfig } from \"./IMySqlEntityStorageConnectorConfig.js\";\n\n/**\n * The options for the MySql entity storage connector constructor.\n */\nexport interface IMySqlEntityStorageConnectorConstructorOptions {\n\t/**\n\t * The schema for the entity.\n\t */\n\tentitySchema: string;\n\n\t/**\n\t * The keys to use from the context ids to create partitions.\n\t */\n\tpartitionContextIds?: string[];\n\n\t/**\n\t * The type of logging component to use.\n\t * @default logging\n\t */\n\tloggingComponentType?: string;\n\n\t/**\n\t * The configuration for the connector.\n\t */\n\tconfig: IMySqlEntityStorageConnectorConfig;\n}\n"]}
+{"version":3,"file":"IMySqlEntityStorageConnectorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IMySqlEntityStorageConnectorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMySqlEntityStorageConnectorConfig } from \"./IMySqlEntityStorageConnectorConfig.js\";\n\n/**\n * The options for the MySql entity storage connector constructor.\n */\nexport interface IMySqlEntityStorageConnectorConstructorOptions {\n\t/**\n\t * The schema for the entity.\n\t */\n\tentitySchema: string;\n\n\t/**\n\t * The keys to use from the context ids to create partitions.\n\t */\n\tpartitionContextIds?: string[];\n\n\t/**\n\t * The type of logging component to use.\n\t */\n\tloggingComponentType?: string;\n\n\t/**\n\t * The configuration for the connector.\n\t */\n\tconfig: IMySqlEntityStorageConnectorConfig;\n}\n"]}

package/dist/es/mysqlEntityStorageConnector.js

@@ -1,8 +1,9 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 import { ContextIdHelper, ContextIdStore } from "@twin.org/context";
-import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, Is, ObjectHelper, SharedStore } from "@twin.org/core";
+import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, HealthStatus, Is, ObjectHelper, SharedStore, Validation } from "@twin.org/core";
 import { ComparisonOperator, EntitySchemaFactory, EntitySchemaHelper, EntitySchemaPropertyType, LogicalOperator, SortDirection } from "@twin.org/entity";
+import { EntityStorageHelper } from "@twin.org/entity-storage-models";
 import { createPool } from "mysql2/promise";
 /**
  * Class for performing entity storage operations using MySql.
@@ -27,6 +28,11 @@ export class MySqlEntityStorageConnector {
      * @internal
      */
     static _PARTITION_KEY_VALUE = "root";
+    /**
+     * The name for the schema.
+     * @internal
+     */
+    _entitySchemaName;
     /**
      * The schema for the entity.
      * @internal
@@ -65,6 +71,7 @@ export class MySqlEntityStorageConnector {
         Guards.stringValue(MySqlEntityStorageConnector.CLASS_NAME, "options.config.password", options.config.password);
         Guards.stringValue(MySqlEntityStorageConnector.CLASS_NAME, "options.config.database", options.config.database);
         Guards.stringValue(MySqlEntityStorageConnector.CLASS_NAME, "options.config.tableName", options.config.tableName);
+        this._entitySchemaName = options.entitySchema;
         this._entitySchema = EntitySchemaFactory.get(options.entitySchema);
         this._partitionContextIds = options.partitionContextIds;
         this._primaryKeyProperty = EntitySchemaHelper.getPrimaryKey(this._entitySchema);
@@ -77,6 +84,34 @@ export class MySqlEntityStorageConnector {
     className() {
         return MySqlEntityStorageConnector.CLASS_NAME;
     }
+    /**
+     * Get the health of the component.
+     * @returns The health of the component.
+     */
+    async health() {
+        try {
+            await this.getPool().query(`SELECT 1 FROM \`${this._config.database}\`.\`${this._config.tableName}\` LIMIT 0`);
+            return [
+                {
+                    source: MySqlEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Ok,
+                    description: "healthDescription",
+                    data: { database: this._config.database, tableName: this._config.tableName }
+                }
+            ];
+        }
+        catch {
+            return [
+                {
+                    source: MySqlEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    description: "healthDescription",
+                    message: "connectionFailed",
+                    data: { database: this._config.database, tableName: this._config.tableName }
+                }
+            ];
+        }
+    }
     /**
      * Get the schema for the entities.
      * @returns The schema for the entities.
@@ -165,7 +200,22 @@ export class MySqlEntityStorageConnector {
      * @returns Nothing.
      */
     async stop(nodeLoggingComponentType) {
-        await this.close();
+        if (this._pool) {
+            const poolConfig = this.createPoolConfig();
+            const poolId = `${poolConfig.host}|${poolConfig.port}|${poolConfig.user}`;
+            let sharedPools = SharedStore.get("mySqlPools");
+            sharedPools ??= {};
+            if (sharedPools[poolId]) {
+                // Decrease the use counter and close the pool if no longer used
+                sharedPools[poolId].useCounter--;
+                if (sharedPools[poolId].useCounter <= 0) {
+                    await this._pool.end();
+                    delete sharedPools[poolId];
+                }
+                SharedStore.set("mySqlPools", sharedPools);
+            }
+            this._pool = undefined;
+        }
     }
     /**
      * Get an entity from MySql.
@@ -200,9 +250,10 @@ export class MySqlEntityStorageConnector {
             const query = `SELECT * FROM \`${this._config.database}\`.\`${this._config.tableName}\` WHERE ${whereClauses.join(" AND ")} LIMIT 1`;
             const [rows] = await pool.query(query, values);
             if (Is.array(rows) && rows.length === 1) {
-                const item = ObjectHelper.removeEmptyProperties(rows[0], { removeNull: true });
-                ObjectHelper.propertyDelete(item, MySqlEntityStorageConnector._PARTITION_KEY);
-                return item;
+                const item = EntityStorageHelper.unPrepareEntity(rows[0], [
+                    MySqlEntityStorageConnector._PARTITION_KEY
+                ]);
+                return this.coerceEntityTypes(item);
             }
         }
         catch (err) {
@@ -222,8 +273,13 @@ export class MySqlEntityStorageConnector {
         Guards.object(MySqlEntityStorageConnector.CLASS_NAME, "entity", entity);
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
-        EntitySchemaHelper.validateEntity(entity, this._entitySchema);
-        const id = entity[this._primaryKeyProperty.property];
+        const prepared = EntityStorageHelper.prepareEntity(entity, this._entitySchema, [
+            {
+                property: MySqlEntityStorageConnector._PARTITION_KEY,
+                value: partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE
+            }
+        ], { nullBehavior: "nullify" });
+        const id = prepared[this._primaryKeyProperty.property];
         try {
             if (Is.arrayValue(conditions)) {
                 const itemData = await this.get(id);
@@ -231,25 +287,25 @@ export class MySqlEntityStorageConnector {
                     return;
                 }
             }
-            const finalEntity = ObjectHelper.clone(entity);
             const props = [...(this._entitySchema.properties ?? [])];
             props.unshift({
                 property: MySqlEntityStorageConnector._PARTITION_KEY,
                 type: EntitySchemaPropertyType.String
             });
-            ObjectHelper.propertySet(finalEntity, MySqlEntityStorageConnector._PARTITION_KEY, partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE);
             const keys = [];
             const values = [];
             for (const prop of props) {
-                if (!(Is.empty(finalEntity[prop.property]) && (prop.optional ?? false))) {
-                    keys.push(prop.property);
-                    if (prop.type === EntitySchemaPropertyType.Object ||
-                        prop.type === EntitySchemaPropertyType.Array) {
-                        values.push(JSON.stringify(finalEntity[prop.property]));
-                    }
-                    else {
-                        values.push(finalEntity[prop.property]);
-                    }
+                keys.push(prop.property);
+                const val = prepared[prop.property];
+                if (val === null || val === undefined) {
+                    values.push(null);
+                }
+                else if (prop.type === EntitySchemaPropertyType.Object ||
+                    prop.type === EntitySchemaPropertyType.Array) {
+                    values.push(JSON.stringify(val));
+                }
+                else {
+                    values.push(val);
                 }
             }
             let sql = `INSERT INTO \`${this._config.database}\`.\`${this._config.tableName}\``;
@@ -265,6 +321,68 @@ export class MySqlEntityStorageConnector {
             }, err);
         }
     }
+    /**
+     * Set multiple entities in a batch.
+     * @param entities The entities to set.
+     * @returns Nothing.
+     */
+    async setBatch(entities) {
+        Guards.arrayValue(MySqlEntityStorageConnector.CLASS_NAME, "entities", entities);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const preparedEntities = entities.map(entity => EntityStorageHelper.prepareEntity(entity, this._entitySchema, [
+            {
+                property: MySqlEntityStorageConnector._PARTITION_KEY,
+                value: partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE
+            }
+        ], { nullBehavior: "nullify" }));
+        try {
+            const props = [...(this._entitySchema.properties ?? [])];
+            props.unshift({
+                property: MySqlEntityStorageConnector._PARTITION_KEY,
+                type: EntitySchemaPropertyType.String
+            });
+            const keys = props.map(p => p.property);
+            const allValues = [];
+            for (const prepared of preparedEntities) {
+                for (const prop of props) {
+                    const val = prepared[prop.property];
+                    if (prop.type === EntitySchemaPropertyType.Object ||
+                        prop.type === EntitySchemaPropertyType.Array) {
+                        allValues.push(Is.empty(val) ? null : JSON.stringify(val));
+                    }
+                    else {
+                        allValues.push(Is.empty(val) ? null : val);
+                    }
+                }
+            }
+            const rowPlaceholder = `(${keys.map(() => "?").join(", ")})`;
+            let sql = `INSERT INTO \`${this._config.database}\`.\`${this._config.tableName}\``;
+            sql += ` (${keys.map(key => `\`${key}\``).join(", ")})`;
+            sql += ` VALUES ${entities.map(() => rowPlaceholder).join(", ")}`;
+            sql += ` ON DUPLICATE KEY UPDATE ${keys.map(key => `\`${key}\` = VALUES(\`${key}\`)`).join(", ")};`;
+            const pool = this.getPool();
+            await pool.query(sql, allValues);
+        }
+        catch (err) {
+            throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "setBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Empty the entity storage.
+     * @returns Nothing.
+     */
+    async empty() {
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const pool = this.getPool();
+            await pool.query(`DELETE FROM \`${this._config.database}\`.\`${this._config.tableName}\` WHERE \`${MySqlEntityStorageConnector._PARTITION_KEY}\` = ?`, [partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE]);
+        }
+        catch (err) {
+            throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "emptyFailed", undefined, err);
+        }
+    }
     /**
      * Remove the entity.
      * @param id The id of the entity to remove.
@@ -301,6 +419,67 @@ export class MySqlEntityStorageConnector {
             }, err);
         }
     }
+    /**
+     * Teardown the entity storage by dropping the table.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns True if the teardown process was successful.
+     */
+    async teardown(nodeLoggingComponentType) {
+        const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
+        await nodeLogging?.log({
+            level: "info",
+            source: MySqlEntityStorageConnector.CLASS_NAME,
+            ts: Date.now(),
+            message: "tableDropping",
+            data: { tableName: this._config.tableName }
+        });
+        try {
+            if (await this.tableExists()) {
+                const pool = this.getPool();
+                await pool.query(`DROP TABLE \`${this._config.database}\`.\`${this._config.tableName}\`;`);
+                await this.waitForTableNotExists();
+            }
+            await nodeLogging?.log({
+                level: "info",
+                source: MySqlEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "tableDropped",
+                data: { tableName: this._config.tableName }
+            });
+            return true;
+        }
+        catch (err) {
+            await nodeLogging?.log({
+                level: "error",
+                source: MySqlEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "teardownFailed",
+                error: BaseError.fromError(err)
+            });
+            return false;
+        }
+    }
+    /**
+     * Remove multiple entities by their primary key IDs.
+     * @param ids The ids of the entities to remove.
+     * @returns Nothing.
+     */
+    async removeBatch(ids) {
+        Guards.arrayValue(MySqlEntityStorageConnector.CLASS_NAME, "ids", ids);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const pool = this.getPool();
+            const sql = `DELETE FROM \`${this._config.database}\`.\`${this._config.tableName}\` WHERE \`${MySqlEntityStorageConnector._PARTITION_KEY}\` = ? AND \`${String(this._primaryKeyProperty.property)}\` IN (?)`;
+            await pool.query(sql, [
+                partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE,
+                ids
+            ]);
+        }
+        catch (err) {
+            throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "removeBatchFailed", undefined, err);
+        }
+    }
     /**
      * Find all the entities which match the conditions.
      * @param conditions The conditions to match for the entities.
@@ -314,6 +493,13 @@ export class MySqlEntityStorageConnector {
     async query(conditions, sortProperties, properties, cursor, limit) {
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        EntityStorageHelper.validateSortProperties(this._entitySchema, sortProperties);
+        EntityStorageHelper.validateProperties(this._entitySchema, properties);
+        if (!Is.empty(limit)) {
+            const validationFailures = [];
+            Validation.integer("limit", limit, validationFailures, undefined, { minValue: 1 });
+            Validation.asValidationError(MySqlEntityStorageConnector.CLASS_NAME, "query", validationFailures);
+        }
         let sql = "";
         try {
             const returnSize = limit ?? MySqlEntityStorageConnector._DEFAULT_LIMIT;
@@ -326,37 +512,27 @@ export class MySqlEntityStorageConnector {
                 }
                 orderByClause = `ORDER BY ${orderClauses.join(", ")}`;
             }
-            const whereClauses = [];
-            const values = [];
-            const finalConditions = {
-                conditions: [],
-                logicalOperator: LogicalOperator.And
-            };
-            finalConditions.conditions.push({
-                property: MySqlEntityStorageConnector._PARTITION_KEY,
-                comparison: ComparisonOperator.Equals,
-                value: partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE
-            });
-            if (!Is.empty(conditions)) {
-                finalConditions.conditions.push(conditions);
-            }
-            this.buildQueryParameters("", finalConditions, whereClauses, values);
+            const { whereClauses, values } = this.buildWhereClause(conditions, partitionKey);
             const startIndex = Coerce.number(cursor) ?? 0;
             sql = `SELECT ${properties ? properties.map(p => `\`${String(p)}\``).join(", ") : "*"} FROM \`${this._config.database}\`.\`${this._config.tableName}\``;
-            sql += ` WHERE ${whereClauses.join(" AND ")} ${orderByClause}`;
-            sql += ` LIMIT ${returnSize} OFFSET ${startIndex}`;
+            if (whereClauses.length > 0) {
+                sql += ` WHERE ${whereClauses.join(" AND ")}`;
+            }
+            sql += ` ${orderByClause} LIMIT ${returnSize + 1} OFFSET ${startIndex}`;
             const pool = this.getPool();
             const [rows] = (await pool.query(sql, values)) ?? [];
-            const entities = rows;
+            const hasMore = Is.array(rows) && rows.length > returnSize;
+            const resultRows = hasMore ? rows.slice(0, returnSize) : rows;
+            const entities = resultRows;
             for (let i = 0; i < entities.length; i++) {
-                entities[i] = ObjectHelper.removeEmptyProperties(entities[i], { removeNull: true });
-                ObjectHelper.propertyDelete(entities[i], MySqlEntityStorageConnector._PARTITION_KEY);
+                entities[i] = EntityStorageHelper.unPrepareEntity(entities[i], [
+                    MySqlEntityStorageConnector._PARTITION_KEY
+                ]);
+                entities[i] = this.coerceEntityTypes(entities[i]);
             }
             return {
                 entities,
-                cursor: Is.array(rows) && rows.length === returnSize
-                    ? Coerce.string(startIndex + returnSize)
-                    : undefined
+                cursor: hasMore ? Coerce.string(startIndex + returnSize) : undefined
             };
         }
         catch (err) {
@@ -364,36 +540,99 @@ export class MySqlEntityStorageConnector {
         }
     }
     /**
-     * Drop the table.
-     * @returns Nothing.
+     * Count all the entities which match the conditions.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The total count of entities in the storage.
      */
-    async tableDrop() {
+    async count(conditions) {
+        let sql;
         try {
-            if (await this.tableExists()) {
-                const pool = this.getPool();
-                await pool.query(`DROP TABLE \`${this._config.database}\`.\`${this._config.tableName}\`;`);
-                await this.waitForTableNotExists();
+            const pool = this.getPool();
+            const contextIds = await ContextIdStore.getContextIds();
+            const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+            const { whereClauses, values } = this.buildWhereClause(conditions, partitionKey);
+            sql = `SELECT COUNT(*) AS count FROM \`${this._config.database}\`.\`${this._config.tableName}\``;
+            if (whereClauses.length > 0) {
+                sql += ` WHERE ${whereClauses.join(" AND ")}`;
             }
+            const [rows] = await pool.query(sql, values);
+            return Number(rows[0].count);
         }
-        catch {
-            // Ignore errors
+        catch (err) {
+            throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "countFailed", { sql }, err);
         }
     }
     /**
-     * Empty the table.
-     * @returns Nothing.
+     * Get all unique partition context ids present in the table.
+     * @returns An array of context id objects, one per unique partition.
      */
-    async tableEmpty() {
+    async getPartitionContextIds() {
+        if (!Is.arrayValue(this._partitionContextIds)) {
+            return [];
+        }
         try {
-            if (await this.tableExists()) {
-                const pool = this.getPool();
-                await pool.query(`TRUNCATE TABLE \`${this._config.database}\`.\`${this._config.tableName}\`;`);
-            }
+            const pool = this.getPool();
+            const [rows] = await pool.query(`SELECT DISTINCT \`${MySqlEntityStorageConnector._PARTITION_KEY}\` FROM \`${this._config.database}\`.\`${this._config.tableName}\``);
+            return rows
+                .map(row => row[MySqlEntityStorageConnector._PARTITION_KEY])
+                .filter((id) => Is.stringValue(id))
+                .map(id => ContextIdHelper.shortSplit(this._partitionContextIds ?? [], id));
         }
-        catch {
-            // Ignore errors
+        catch (err) {
+            throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "getPartitionContextIdsFailed", undefined, err);
         }
     }
+    /**
+     * Create the target connector for performing the migration using a temporary table.
+     * @param newEntitySchema The name of the new entity schema to create the connector for.
+     * @returns Connector for performing the migration.
+     */
+    async createTargetConnector(newEntitySchema) {
+        const migrationTableName = `${this._config.tableName}Migration${Date.now()}`;
+        return new MySqlEntityStorageConnector({
+            entitySchema: newEntitySchema,
+            config: {
+                ...this._config,
+                tableName: migrationTableName
+            },
+            partitionContextIds: this._partitionContextIds
+        });
+    }
+    /**
+     * Finalize the migration by dropping the source table and renaming the migration table to the original name.
+     * @param targetConnector The connector holding the migrated data in a temporary table.
+     * @param options The options to control how the migration is finalized.
+     * @param loggingComponentType The logging component type to use during finalization.
+     * @returns The final connector using the original table name with the new schema.
+     */
+    async finalizeMigration(targetConnector, options, loggingComponentType) {
+        // Teardown the existing table with the original name to free up the name for the new table
+        await this.teardown(loggingComponentType);
+        // RENAME TABLE is an atomic metadata-only operation in MySQL — no data copying needed.
+        const pool = this.getPool();
+        await pool.query(`RENAME TABLE \`${targetConnector._config.database}\`.\`${targetConnector._config.tableName}\` TO \`${this._config.database}\`.\`${this._config.tableName}\``);
+        const finalConnector = new MySqlEntityStorageConnector({
+            entitySchema: targetConnector._entitySchemaName,
+            config: this._config,
+            partitionContextIds: this._partitionContextIds
+        });
+        if (await finalConnector.bootstrap(loggingComponentType)) {
+            await targetConnector.stop();
+            return finalConnector;
+        }
+        throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "finalizeMigrationFailedBootstrap", undefined);
+    }
+    /**
+     * Cleanup a failed or aborted migration by dropping the temporary migration table.
+     * @param targetConnector The target connector to cleanup.
+     * @param options The options to control how the migration is cleaned up.
+     * @param loggingComponentType The optional component type to use for logging.
+     * @returns A promise that resolves when the cleanup is complete.
+     */
+    async cleanupMigration(targetConnector, options, loggingComponentType) {
+        // If something failed the only thing to cleanup is the migration table
+        await targetConnector?.teardown?.(loggingComponentType);
+    }
     /**
      * Check if the database exists.
      * @returns True if the database exists, false otherwise.
@@ -431,6 +670,22 @@ export class MySqlEntityStorageConnector {
             this._pool = undefined;
         }
     }
+    /**
+     * Coerce MySQL raw row values back to proper TypeScript types based on the entity schema.
+     * MySQL returns TINYINT(1) as 0/1 rather than false/true; this method converts those.
+     * @param entity The raw entity row from MySQL.
+     * @returns The entity with schema-correct types.
+     * @internal
+     */
+    coerceEntityTypes(entity) {
+        for (const prop of this._entitySchema.properties ?? []) {
+            const value = entity[prop.property];
+            if (prop.type === EntitySchemaPropertyType.Boolean && !Is.empty(value)) {
+                ObjectHelper.propertySet(entity, prop.property, Boolean(value));
+            }
+        }
+        return entity;
+    }
     /**
      * Wait for a database to exist.
      * @returns Nothing.
@@ -537,6 +792,31 @@ export class MySqlEntityStorageConnector {
             queueLimit: poolConfig.queueLimit ?? 0
         };
     }
+    /**
+     * Build where clause arrays for a query, combining partition key and optional conditions.
+     * @param conditions The optional entity conditions to include.
+     * @param partitionKey The partition key value.
+     * @returns The where clauses and bound values.
+     * @internal
+     */
+    buildWhereClause(conditions, partitionKey) {
+        const whereClauses = [];
+        const values = [];
+        const finalConditions = {
+            conditions: [],
+            logicalOperator: LogicalOperator.And
+        };
+        finalConditions.conditions.push({
+            property: MySqlEntityStorageConnector._PARTITION_KEY,
+            comparison: ComparisonOperator.Equals,
+            value: partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE
+        });
+        if (!Is.empty(conditions)) {
+            finalConditions.conditions.push(conditions);
+        }
+        this.buildQueryParameters("", finalConditions, whereClauses, values);
+        return { whereClauses, values };
+    }
     /**
      * Create an SQL condition clause.
      * @param objectPath The path for the nested object.
@@ -589,6 +869,11 @@ export class MySqlEntityStorageConnector {
         prop += comparator.property;
         if (comparator.comparison === ComparisonOperator.In) {
             const inValues = Is.array(comparator.value) ? comparator.value : [comparator.value];
+            if (inValues.length === 0) {
+                // MySQL rejects `IN ()` as a syntax error — short-circuit to a condition
+                // that is always false so the query returns zero rows cleanly (#141).
+                return "1 = 0";
+            }
             values.push(...inValues.map(val => this.propertyToDbValue(val, type)));
             const placeholders = inValues.map(() => "?").join(", ");
             return `\`${prop}\` IN (${placeholders})`;
@@ -667,8 +952,20 @@ export class MySqlEntityStorageConnector {
                     values.push(`%${String(comparator.value).toLowerCase()}%`);
                     return `LOWER(\`${prop}\`) LIKE ?`;
                 }
+                values.pop();
+                values.push(JSON.stringify(comparator.value));
                 return `JSON_CONTAINS(\`${prop}\`, ?)`;
             }
+            case ComparisonOperator.NotIncludes: {
+                if (type === EntitySchemaPropertyType.String) {
+                    values.pop();
+                    values.push(`%${String(comparator.value).toLowerCase()}%`);
+                    return `LOWER(\`${prop}\`) NOT LIKE ?`;
+                }
+                values.pop();
+                values.push(JSON.stringify(comparator.value));
+                return `NOT JSON_CONTAINS(\`${prop}\`, ?)`;
+            }
             default:
                 throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "comparisonNotSupported", {
                     comparison: comparator.comparison
@@ -693,7 +990,7 @@ export class MySqlEntityStorageConnector {
             return Number(value);
         }
         else if (type === "boolean") {
-            return Boolean(value);
+            return value ? 1 : 0;
         }
         return value;
     }
@@ -718,6 +1015,8 @@ export class MySqlEntityStorageConnector {
     /**
      * Verify the conditions for the entity.
      * @param conditions The conditions to verify.
+     * @param obj The object to verify the conditions against.
+     * @returns True if all conditions are met, false otherwise.
      * @internal
      */
     verifyConditions(conditions, obj) {
@@ -725,10 +1024,13 @@ export class MySqlEntityStorageConnector {
     }
     /**
      * Map entity schema properties to SQL properties.
+     * @param schema The schema to use, defaults to the connector's own schema.
      * @returns The SQL properties as a string.
      * @throws GeneralError if the entity properties do not exist.
+     * @internal
      */
-    mapMySqlProperties() {
+    mapMySqlProperties(schema) {
+        const entitySchema = schema ?? this._entitySchema;
         const sqlTypeMap = {
             [EntitySchemaPropertyType.String]: "LONGTEXT",
             [EntitySchemaPropertyType.Number]: "FLOAT",
@@ -737,11 +1039,11 @@ export class MySqlEntityStorageConnector {
             [EntitySchemaPropertyType.Array]: "JSON",
             [EntitySchemaPropertyType.Boolean]: "TINYINT(1)"
         };
-        if (!this._entitySchema.properties) {
+        if (!entitySchema.properties) {
             throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "entitySchemaPropertiesUndefined");
         }
         const primaryKeys = [];
-        const props = [...this._entitySchema.properties];
+        const props = [...entitySchema.properties];
         props.unshift({
             property: MySqlEntityStorageConnector._PARTITION_KEY,
             type: EntitySchemaPropertyType.String,
@@ -752,7 +1054,7 @@ export class MySqlEntityStorageConnector {
             let sqlType = sqlTypeMap[prop.type] || "TEXT";
             if (prop.format) {
                 switch (prop.type) {
-                    case "string":
+                    case EntitySchemaPropertyType.String:
                         sqlType = "LONGTEXT";
                         switch (prop.format) {
                             case "uuid":
@@ -764,7 +1066,7 @@ export class MySqlEntityStorageConnector {
                                 break;
                         }
                         break;
-                    case "number":
+                    case EntitySchemaPropertyType.Number:
                         sqlType = "FLOAT";
                         switch (prop.format) {
                             case "float":
@@ -775,7 +1077,7 @@ export class MySqlEntityStorageConnector {
                                 break;
                         }
                         break;
-                    case "integer":
+                    case EntitySchemaPropertyType.Integer:
                         sqlType = "INT";
                         switch (prop.format) {
                             case "int8":