@twin.org/entity-storage-connector-mysql 0.0.3-next.2 → 0.0.3-next.21

package/dist/es/mysqlEntityStorageConnector.js

@@ -1,9 +1,10 @@
 // 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 { 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
@@ -43,10 +49,10 @@ export class MySqlEntityStorageConnector {
      */
     _config;
     /**
-     * The configuration for the connector.
+     * The connection pool for MySql.
      * @internal
      */
-    _connection;
+    _pool;
     /**
      * The primary key property.
      * @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.
@@ -92,7 +127,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 +139,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 +164,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 +194,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 +229,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,11 +248,12 @@ 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);
-                return item;
+                const item = EntityStorageHelper.unPrepareEntity(rows[0], [
+                    MySqlEntityStorageConnector._PARTITION_KEY
+                ]);
+                return this.coerceEntityTypes(item);
             }
         }
         catch (err) {
@@ -214,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);
@@ -223,38 +287,100 @@ 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);
+                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}\``;
+            sql += ` (${keys.map(key => `\`${key}\``).join(", ")})`;
+            sql += ` VALUES (${values.map(() => "?").join(", ")})`;
+            sql += ` ON DUPLICATE KEY UPDATE ${keys.map(key => `\`${key}\` = VALUES(\`${key}\`)`).join(", ")};`;
+            const pool = this.getPool();
+            await pool.query(sql, values);
+        }
+        catch (err) {
+            throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "setFailed", {
+                id
+            }, 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) {
-                        values.push(JSON.stringify(finalEntity[prop.property]));
+                        allValues.push(Is.empty(val) ? null : JSON.stringify(val));
                     }
                     else {
-                        values.push(finalEntity[prop.property]);
+                        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 (${values.map(() => "?").join(", ")})`;
+            sql += ` VALUES ${entities.map(() => rowPlaceholder).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, allValues);
         }
         catch (err) {
-            throw new GeneralError(MySqlEntityStorageConnector.CLASS_NAME, "setFailed", {
-                id
-            }, 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);
         }
     }
     /**
@@ -268,7 +394,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 +410,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 +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.
@@ -318,37 +505,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}`;
-            const dbConnection = await this.createConnection();
-            const [rows] = (await dbConnection.query(sql, values)) ?? [];
-            const entities = rows;
+            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 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) {
@@ -356,50 +533,152 @@ 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 dbConnection = await this.createConnection();
-                await dbConnection.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 dbConnection = await this.createConnection();
-                await dbConnection.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.
      */
     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 {
             return false;
         }
     }
+    /**
+     * Close the connection pool and release all connections.
+     * Should be called when the connector is no longer needed.
+     * @returns Nothing.
+     */
+    async 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;
+        }
+    }
+    /**
+     * 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.
@@ -421,8 +700,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,31 +740,76 @@ 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
         };
     }
+    /**
+     * 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.
@@ -536,42 +860,106 @@ 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];
+            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})`;
         }
+        // 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}\`, ?)`;
+            }
+            case ComparisonOperator.NotIncludes: {
+                if (type === EntitySchemaPropertyType.String) {
+                    values.pop();
+                    values.push(`%${String(comparator.value).toLowerCase()}%`);
+                    return `LOWER(\`${prop}\`) NOT LIKE ?`;
+                }
+                return `NOT 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.
@@ -591,7 +979,7 @@ export class MySqlEntityStorageConnector {
             return Number(value);
         }
         else if (type === "boolean") {
-            return Boolean(value);
+            return value ? 1 : 0;
         }
         return value;
     }
@@ -623,10 +1011,12 @@ 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.
      */
-    mapMySqlProperties() {
+    mapMySqlProperties(schema) {
+        const entitySchema = schema ?? this._entitySchema;
         const sqlTypeMap = {
             [EntitySchemaPropertyType.String]: "LONGTEXT",
             [EntitySchemaPropertyType.Number]: "FLOAT",
@@ -635,11 +1025,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,
@@ -650,7 +1040,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":
@@ -662,7 +1052,7 @@ export class MySqlEntityStorageConnector {
                                 break;
                         }
                         break;
-                    case "number":
+                    case EntitySchemaPropertyType.Number:
                         sqlType = "FLOAT";
                         switch (prop.format) {
                             case "float":
@@ -673,7 +1063,7 @@ export class MySqlEntityStorageConnector {
                                 break;
                         }
                         break;
-                    case "integer":
+                    case EntitySchemaPropertyType.Integer:
                         sqlType = "INT";
                         switch (prop.format) {
                             case "int8":