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

package/README.md

@@ -1,6 +1,6 @@
-# TWIN Entity Storage Connector MySQL
+# Entity Storage Connector MySQL
 
-Entity Storage connector implementation using MySQL storage.
+This package provides a MySQL backend for relational persistence and SQL-based access patterns. It is designed to work with the wider storage ecosystem so applications can keep behaviour consistent across connectors and environments.
 
 ## Installation
 
@@ -8,18 +8,13 @@ Entity Storage connector implementation using MySQL storage.
 npm install @twin.org/entity-storage-connector-mysql
 ```
 
-## Testing
+## Docker
 
-The tests developed are functional tests and need an instance of MySql up and running. To run MySql locally:
+To perform testing of this component it may be necessary to launch a local instance to communicate with.
 
-```sh
-docker run -p 3400:3306 --name twin-entity-storage-mysql --hostname mysql -e MYSQL_ROOT_PASSWORD=password -d mysql:latest
-```
-
-Afterwards you can run the tests as follows:
-
-```sh
-npm run test
+```shell
+docker pull mysql:latest
+docker run -d --name twin-entity-storage-mysql -e MYSQL_ROOT_PASSWORD=password -p 3400:3306 mysql:latest
 ```
 
 ## Examples

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

@@ -1 +1 @@
-{"version":3,"file":"IMySqlEntityStorageConnectorConfig.js","sourceRoot":"","sources":["../../../src/models/IMySqlEntityStorageConnectorConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the MySql Entity Storage Connector.\n */\nexport interface IMySqlEntityStorageConnectorConfig {\n\t/**\n\t * The host for the MySql instance.\n\t */\n\thost: string;\n\n\t/**\n\t * The port for the MySql instance.\n\t */\n\tport?: number;\n\n\t/**\n\t * The user for the MySql instance.\n\t */\n\tuser: string;\n\n\t/**\n\t * The password for the MySql instance.\n\t */\n\tpassword: string;\n\n\t/**\n\t * The name of the database to be used.\n\t */\n\tdatabase: string;\n\n\t/**\n\t * The name of the table to be used.\n\t */\n\ttableName: string;\n}\n"]}
+{"version":3,"file":"IMySqlEntityStorageConnectorConfig.js","sourceRoot":"","sources":["../../../src/models/IMySqlEntityStorageConnectorConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the MySql Entity Storage Connector.\n */\nexport interface IMySqlEntityStorageConnectorConfig {\n\t/**\n\t * The host for the MySql instance.\n\t */\n\thost: string;\n\n\t/**\n\t * The port for the MySql instance.\n\t */\n\tport?: number;\n\n\t/**\n\t * The user for the MySql instance.\n\t */\n\tuser: string;\n\n\t/**\n\t * The password for the MySql instance.\n\t */\n\tpassword: string;\n\n\t/**\n\t * The name of the database to be used.\n\t */\n\tdatabase: string;\n\n\t/**\n\t * The name of the table to be used.\n\t */\n\ttableName: string;\n\n\t/**\n\t * Optional connection pool configuration.\n\t */\n\tpool?: {\n\t\t/**\n\t\t * Maximum number of connections in pool.\n\t\t * @default 10\n\t\t */\n\t\tconnectionLimit?: number;\n\n\t\t/**\n\t\t * Maximum number of idle connections.\n\t\t * @default 10\n\t\t */\n\t\tmaxIdle?: number;\n\n\t\t/**\n\t\t * Time in ms before removing idle connection.\n\t\t * @default 60000 (1 minute)\n\t\t */\n\t\tidleTimeout?: number;\n\n\t\t/**\n\t\t * Enable TCP keep-alive.\n\t\t * @default true\n\t\t */\n\t\tenableKeepAlive?: boolean;\n\n\t\t/**\n\t\t * Wait for available connection when pool is full.\n\t\t * @default true\n\t\t */\n\t\twaitForConnections?: boolean;\n\n\t\t/**\n\t\t * Maximum queued requests (0 = unlimited).\n\t\t * @default 0\n\t\t */\n\t\tqueueLimit?: number;\n\t};\n}\n"]}

package/dist/es/mysqlEntityStorageConnector.js

@@ -1,9 +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 } from "@twin.org/core";
+import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, HealthStatus, Is, ObjectHelper, SharedStore } from "@twin.org/core";
 import { ComparisonOperator, EntitySchemaFactory, EntitySchemaHelper, EntitySchemaPropertyType, LogicalOperator, SortDirection } from "@twin.org/entity";
-import { createConnection } from "mysql2/promise";
+import { createPool } from "mysql2/promise";
 /**
  * Class for performing entity storage operations using MySql.
  */
@@ -43,10 +43,10 @@ export class MySqlEntityStorageConnector {
      */
     _config;
     /**
-     * The configuration for the connector.
+     * The connection pool for MySql.
      * @internal
      */
-    _connection;
+    _pool;
     /**
      * The primary key property.
      * @internal
@@ -77,6 +77,32 @@ 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"
+                }
+            ];
+        }
+        catch {
+            return [
+                {
+                    source: MySqlEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    description: "healthDescription",
+                    message: "connectionFailed"
+                }
+            ];
+        }
+    }
     /**
      * Get the schema for the entities.
      * @returns The schema for the entities.
@@ -92,7 +118,7 @@ export class MySqlEntityStorageConnector {
     async bootstrap(nodeLoggingComponentType) {
         const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
         try {
-            const dbConnection = await this.createConnection();
+            const pool = this.getPool();
             const databaseExists = await this.databaseExists();
             if (!databaseExists) {
                 await nodeLogging?.log({
@@ -104,7 +130,7 @@ export class MySqlEntityStorageConnector {
                         databaseName: this._config.database
                     }
                 });
-                await dbConnection.query(`CREATE DATABASE IF NOT EXISTS \`${this._config.database}\``);
+                await pool.query(`CREATE DATABASE IF NOT EXISTS \`${this._config.database}\``);
                 await this.waitForDatabaseExists();
             }
             else {
@@ -129,7 +155,7 @@ export class MySqlEntityStorageConnector {
                         tableName: this._config.tableName
                     }
                 });
-                await dbConnection.query(`CREATE TABLE IF NOT EXISTS \`${this._config.database}\`.\`${this._config.tableName}\` (${this.mapMySqlProperties()})`);
+                await pool.query(`CREATE TABLE IF NOT EXISTS \`${this._config.database}\`.\`${this._config.tableName}\` (${this.mapMySqlProperties()})`);
                 await this.waitForTableExists();
             }
             else {
@@ -159,6 +185,29 @@ export class MySqlEntityStorageConnector {
         }
         return true;
     }
+    /**
+     * The component needs to be stopped when the node is closed.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    async stop(nodeLoggingComponentType) {
+        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.
      * @param id The id of the entity to get, or the index value if secondaryIndex is set.
@@ -171,7 +220,7 @@ export class MySqlEntityStorageConnector {
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
         try {
-            const dbConnection = await this.createConnection();
+            const pool = this.getPool();
             const whereClauses = [];
             const values = [];
             whereClauses.push(`\`${MySqlEntityStorageConnector._PARTITION_KEY}\` = ?`);
@@ -190,7 +239,7 @@ export class MySqlEntityStorageConnector {
                 }
             }
             const query = `SELECT * FROM \`${this._config.database}\`.\`${this._config.tableName}\` WHERE ${whereClauses.join(" AND ")} LIMIT 1`;
-            const [rows] = await dbConnection.query(query, values);
+            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);
@@ -248,8 +297,8 @@ export class MySqlEntityStorageConnector {
             sql += ` (${keys.map(key => `\`${key}\``).join(", ")})`;
             sql += ` VALUES (${values.map(() => "?").join(", ")})`;
             sql += ` ON DUPLICATE KEY UPDATE ${keys.map(key => `\`${key}\` = VALUES(\`${key}\`)`).join(", ")};`;
-            const dbConnection = await this.createConnection();
-            await dbConnection.query(sql, values);
+            const pool = this.getPool();
+            await pool.query(sql, values);
         }
         catch (err) {
             throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "setFailed", {
@@ -257,6 +306,67 @@ 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);
+        for (const entity of entities) {
+            EntitySchemaHelper.validateEntity(entity, this._entitySchema);
+        }
+        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 entity of entities) {
+                const finalEntity = ObjectHelper.clone(entity);
+                ObjectHelper.propertySet(finalEntity, MySqlEntityStorageConnector._PARTITION_KEY, partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE);
+                for (const prop of props) {
+                    const val = finalEntity[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.
@@ -268,7 +378,7 @@ export class MySqlEntityStorageConnector {
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
         try {
-            const dbConnection = await this.createConnection();
+            const pool = this.getPool();
             const itemData = await this.get(id, undefined, conditions);
             if (Is.notEmpty(itemData)) {
                 const values = [];
@@ -284,7 +394,7 @@ export class MySqlEntityStorageConnector {
                     }));
                 }
                 const query = `DELETE FROM \`${this._config.database}\`.\`${this._config.tableName}\` WHERE ${whereClauses.join(" AND ")}`;
-                await dbConnection.query(query, values);
+                await pool.query(query, values);
             }
         }
         catch (err) {
@@ -293,6 +403,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.
@@ -337,8 +508,8 @@ export class MySqlEntityStorageConnector {
             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}`;
-            const dbConnection = await this.createConnection();
-            const [rows] = (await dbConnection.query(sql, values)) ?? [];
+            const pool = this.getPool();
+            const [rows] = (await pool.query(sql, values)) ?? [];
             const entities = rows;
             for (let i = 0; i < entities.length; i++) {
                 entities[i] = ObjectHelper.removeEmptyProperties(entities[i], { removeNull: true });
@@ -356,34 +527,19 @@ export class MySqlEntityStorageConnector {
         }
     }
     /**
-     * Drop the table.
-     * @returns Nothing.
+     * Count all the entities which match the conditions.
+     * @returns The total count of entities in the storage.
      */
-    async tableDrop() {
+    async count() {
         try {
-            if (await this.tableExists()) {
-                const dbConnection = await this.createConnection();
-                await dbConnection.query(`DROP TABLE \`${this._config.database}\`.\`${this._config.tableName}\`;`);
-                await this.waitForTableNotExists();
-            }
+            const contextIds = await ContextIdStore.getContextIds();
+            const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+            const pool = this.getPool();
+            const [rows] = await pool.query(`SELECT COUNT(*) AS count FROM \`${this._config.database}\`.\`${this._config.tableName}\` WHERE \`${MySqlEntityStorageConnector._PARTITION_KEY}\` = ?`, [partitionKey ?? MySqlEntityStorageConnector._PARTITION_KEY_VALUE]);
+            return Number(rows[0].count);
         }
-        catch {
-            // Ignore errors
-        }
-    }
-    /**
-     * Empty the table.
-     * @returns Nothing.
-     */
-    async tableEmpty() {
-        try {
-            if (await this.tableExists()) {
-                const dbConnection = await this.createConnection();
-                await dbConnection.query(`TRUNCATE TABLE \`${this._config.database}\`.\`${this._config.tableName}\`;`);
-            }
-        }
-        catch {
-            // Ignore errors
+        catch (err) {
+            throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "countFailed", undefined, err);
         }
     }
     /**
@@ -392,8 +548,8 @@ export class MySqlEntityStorageConnector {
      */
     async databaseExists() {
         try {
-            const dbConnection = await this.createConnection();
-            const [rows] = await dbConnection.query("SHOW DATABASES LIKE ?;", [this._config.database]);
+            const pool = this.getPool();
+            const [rows] = await pool.query("SHOW DATABASES LIKE ?;", [this._config.database]);
             return Is.arrayValue(rows);
         }
         catch {
@@ -421,8 +577,8 @@ export class MySqlEntityStorageConnector {
      */
     async tableExists() {
         try {
-            const dbConnection = await this.createConnection();
-            const [rows] = await dbConnection.query("SHOW TABLES FROM ?? LIKE ?", [
+            const pool = this.getPool();
+            const [rows] = await pool.query("SHOW TABLES FROM ?? LIKE ?", [
                 this._config.database,
                 this._config.tableName
             ]);
@@ -461,29 +617,49 @@ export class MySqlEntityStorageConnector {
         }
     }
     /**
-     * Create a new DB connection.
-     * @returns The MySql connection.
+     * Get or create the connection pool.
+     * @returns The MySql connection pool.
      * @internal
      */
-    async createConnection() {
-        if (this._connection) {
-            return this._connection;
+    getPool() {
+        if (!this._pool) {
+            const poolConfig = this.createPoolConfig();
+            const poolId = `${poolConfig.host}|${poolConfig.port}|${poolConfig.user}`;
+            let sharedPools = SharedStore.get("mySqlPools");
+            sharedPools ??= {};
+            // If there is no pool for the id, create it
+            if (!sharedPools[poolId]) {
+                sharedPools[poolId] = {
+                    pool: createPool(poolConfig),
+                    useCounter: 0
+                };
+                SharedStore.set("mySqlPools", sharedPools);
+            }
+            // Increase the use counter and return the pool
+            sharedPools[poolId].useCounter++;
+            this._pool = sharedPools[poolId].pool;
         }
-        const newConnection = await createConnection(this.createConnectionConfig());
-        this._connection = newConnection;
-        return newConnection;
+        return this._pool;
     }
     /**
-     * Create a new DB connection configuration.
-     * @returns The MySql connection configuration.
+     * Create the connection pool configuration.
+     * @returns The MySql pool configuration.
      * @internal
      */
-    createConnectionConfig() {
+    createPoolConfig() {
+        const poolConfig = this._config.pool ?? {};
         return {
             host: this._config.host,
             port: this._config.port ?? 3306,
             user: this._config.user,
-            password: this._config.password
+            password: this._config.password,
+            connectionLimit: poolConfig.connectionLimit ?? 10,
+            maxIdle: poolConfig.maxIdle ?? 10,
+            idleTimeout: poolConfig.idleTimeout ?? 60000,
+            enableKeepAlive: poolConfig.enableKeepAlive ?? true,
+            keepAliveInitialDelay: 0,
+            waitForConnections: poolConfig.waitForConnections ?? true,
+            queueLimit: poolConfig.queueLimit ?? 0
         };
     }
     /**
@@ -536,42 +712,93 @@ export class MySqlEntityStorageConnector {
             prop += ".";
         }
         prop += comparator.property;
-        // prop = prop.replace(/\./g, "->");
         if (comparator.comparison === ComparisonOperator.In) {
             const inValues = Is.array(comparator.value) ? comparator.value : [comparator.value];
             values.push(...inValues.map(val => this.propertyToDbValue(val, type)));
             const placeholders = inValues.map(() => "?").join(", ");
             return `\`${prop}\` IN (${placeholders})`;
         }
+        // null/undefined must use IS NULL / IS NOT NULL — never a parameterised placeholder.
+        // Passing undefined through propertyToDbValue() coerces it to NaN for number fields
+        // (Number(undefined) === NaN), and null coerces to 0 (Number(null) === 0), both of
+        // which produce semantically wrong or invalid SQL.
+        if (comparator.value === null || comparator.value === undefined) {
+            if (comparator.comparison === ComparisonOperator.Equals ||
+                comparator.comparison === ComparisonOperator.NotEquals) {
+                const nullCheck = comparator.comparison === ComparisonOperator.Equals ? "IS NULL" : "IS NOT NULL";
+                if (comparator.property.split(".").length > 1) {
+                    const rootProp = comparator.property.split(".")[0];
+                    const nestedPath = comparator.property.split(".").slice(1).join(".");
+                    const rootSchema = this._entitySchema.properties?.find(p => p.property === rootProp);
+                    const isArray = rootSchema?.type === EntitySchemaPropertyType.Array;
+                    const jsonPath = isArray ? `$[*].${nestedPath}` : `$.${nestedPath}`;
+                    const jsonExpr = `JSON_UNQUOTE(JSON_EXTRACT(\`${rootProp}\`, '${jsonPath}'))`;
+                    return `${jsonExpr} ${nullCheck}`;
+                }
+                return `\`${prop}\` ${nullCheck}`;
+            }
+        }
         const dbValue = this.propertyToDbValue(comparator.value, type);
         values.push(dbValue);
         if (comparator.property.split(".").length > 1) {
-            return `JSON_UNQUOTE(JSON_EXTRACT(\`${comparator.property.split(".")[0]}\`, '$.${comparator.property.split(".").slice(1).join(".")}')) = ?`;
-        }
-        else if (comparator.comparison === ComparisonOperator.Equals) {
-            return `\`${prop}\` = ?`;
-        }
-        else if (comparator.comparison === ComparisonOperator.NotEquals) {
-            return `\`${prop}\` <> ?`;
-        }
-        else if (comparator.comparison === ComparisonOperator.GreaterThan) {
-            return `\`${prop}\` > ?`;
-        }
-        else if (comparator.comparison === ComparisonOperator.LessThan) {
-            return `\`${prop}\` < ?`;
-        }
-        else if (comparator.comparison === ComparisonOperator.GreaterThanOrEqual) {
-            return `\`${prop}\` >= ?`;
-        }
-        else if (comparator.comparison === ComparisonOperator.LessThanOrEqual) {
-            return `\`${prop}\` <= ?`;
+            const rootProp = comparator.property.split(".")[0];
+            const nestedPath = comparator.property.split(".").slice(1).join(".");
+            const rootSchema = this._entitySchema.properties?.find(p => p.property === rootProp);
+            const isArray = rootSchema?.type === EntitySchemaPropertyType.Array;
+            const jsonPath = isArray ? `$[*].${nestedPath}` : `$.${nestedPath}`;
+            const jsonExpr = `JSON_UNQUOTE(JSON_EXTRACT(\`${rootProp}\`, '${jsonPath}'))`;
+            switch (comparator.comparison) {
+                case ComparisonOperator.Includes: {
+                    values.pop();
+                    values.push(`%${String(comparator.value).toLowerCase()}%`);
+                    return `LOWER(${jsonExpr}) LIKE ?`;
+                }
+                case ComparisonOperator.NotEquals:
+                    return `${jsonExpr} <> ?`;
+                case ComparisonOperator.GreaterThan:
+                    return `${jsonExpr} > ?`;
+                case ComparisonOperator.LessThan:
+                    return `${jsonExpr} < ?`;
+                case ComparisonOperator.GreaterThanOrEqual:
+                    return `${jsonExpr} >= ?`;
+                case ComparisonOperator.LessThanOrEqual:
+                    return `${jsonExpr} <= ?`;
+                default:
+                    return `${jsonExpr} = ?`;
+            }
         }
-        else if (comparator.comparison === ComparisonOperator.Includes) {
-            return `JSON_CONTAINS(\`${prop}\`, ?)`;
+        switch (comparator.comparison) {
+            case ComparisonOperator.Equals:
+                if (Is.object(comparator.value) || Is.array(comparator.value)) {
+                    return `JSON_CONTAINS(\`${prop}\`, ?)`;
+                }
+                return `\`${prop}\` = ?`;
+            case ComparisonOperator.NotEquals:
+                if (Is.object(comparator.value) || Is.array(comparator.value)) {
+                    return `NOT JSON_CONTAINS(\`${prop}\`, ?)`;
+                }
+                return `\`${prop}\` <> ?`;
+            case ComparisonOperator.GreaterThan:
+                return `\`${prop}\` > ?`;
+            case ComparisonOperator.LessThan:
+                return `\`${prop}\` < ?`;
+            case ComparisonOperator.GreaterThanOrEqual:
+                return `\`${prop}\` >= ?`;
+            case ComparisonOperator.LessThanOrEqual:
+                return `\`${prop}\` <= ?`;
+            case ComparisonOperator.Includes: {
+                if (type === EntitySchemaPropertyType.String) {
+                    values.pop();
+                    values.push(`%${String(comparator.value).toLowerCase()}%`);
+                    return `LOWER(\`${prop}\`) LIKE ?`;
+                }
+                return `JSON_CONTAINS(\`${prop}\`, ?)`;
+            }
+            default:
+                throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "comparisonNotSupported", {
+                    comparison: comparator.comparison
+                });
         }
-        throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "comparisonNotSupported", {
-            comparison: comparator.comparison
-        });
     }
     /**
      * Format a value to insert into DB.