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

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

@@ -1 +1 @@
-{"version":3,"file":"IPostgreSqlEntityStorageConnectorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IPostgreSqlEntityStorageConnectorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IPostgreSqlEntityStorageConnectorConfig } from \"./IPostgreSqlEntityStorageConnectorConfig.js\";\n\n/**\n * The options for the PostgreSql entity storage connector constructor.\n */\nexport interface IPostgreSqlEntityStorageConnectorConstructorOptions {\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: IPostgreSqlEntityStorageConnectorConfig;\n}\n"]}
+{"version":3,"file":"IPostgreSqlEntityStorageConnectorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IPostgreSqlEntityStorageConnectorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IPostgreSqlEntityStorageConnectorConfig } from \"./IPostgreSqlEntityStorageConnectorConfig.js\";\n\n/**\n * The options for the PostgreSql entity storage connector constructor.\n */\nexport interface IPostgreSqlEntityStorageConnectorConstructorOptions {\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: IPostgreSqlEntityStorageConnectorConfig;\n}\n"]}

package/dist/es/postgreSqlEntityStorageConnector.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 } from "@twin.org/core";
+import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, HealthStatus, Is, ObjectHelper, 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 postgres from "postgres";
 /**
  * Class for performing entity storage operations using ql.
@@ -27,6 +28,11 @@ export class PostgreSqlEntityStorageConnector {
      * @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 PostgreSqlEntityStorageConnector {
         Guards.stringValue(PostgreSqlEntityStorageConnector.CLASS_NAME, "options.config.password", options.config.password);
         Guards.stringValue(PostgreSqlEntityStorageConnector.CLASS_NAME, "options.config.database", options.config.database);
         Guards.stringValue(PostgreSqlEntityStorageConnector.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);
@@ -153,6 +160,35 @@ export class PostgreSqlEntityStorageConnector {
     className() {
         return PostgreSqlEntityStorageConnector.CLASS_NAME;
     }
+    /**
+     * Get the health of the component.
+     * @returns The health of the component.
+     */
+    async health() {
+        try {
+            const sql = await this.createConnection();
+            await sql `SELECT 1 FROM ${sql(this._config.tableName)} LIMIT 0`;
+            return [
+                {
+                    source: PostgreSqlEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Ok,
+                    description: "healthDescription",
+                    data: { tableName: this._config.tableName }
+                }
+            ];
+        }
+        catch {
+            return [
+                {
+                    source: PostgreSqlEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    description: "healthDescription",
+                    message: "connectionFailed",
+                    data: { tableName: this._config.tableName }
+                }
+            ];
+        }
+    }
     /**
      * The component needs to be stopped when the node is closed.
      * @returns Nothing.
@@ -229,9 +265,9 @@ export class PostgreSqlEntityStorageConnector {
                         }
                     }
                 }
-                const entity = ObjectHelper.removeEmptyProperties(rows[0], { removeNull: true });
-                ObjectHelper.propertyDelete(entity, PostgreSqlEntityStorageConnector._PARTITION_KEY);
-                return entity;
+                return EntityStorageHelper.unPrepareEntity(rows[0], [
+                    PostgreSqlEntityStorageConnector._PARTITION_KEY
+                ]);
             }
         }
         catch (err) {
@@ -251,8 +287,13 @@ export class PostgreSqlEntityStorageConnector {
         Guards.object(PostgreSqlEntityStorageConnector.CLASS_NAME, "entity", entity);
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
-        EntitySchemaHelper.validateEntity(entity, this.getSchema());
-        const id = entity[this._primaryKeyProperty.property];
+        const prepared = EntityStorageHelper.prepareEntity(entity, this._entitySchema, [
+            {
+                property: PostgreSqlEntityStorageConnector._PARTITION_KEY,
+                value: partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE
+            }
+        ], { nullBehavior: "nullify" });
+        const id = prepared[this._primaryKeyProperty.property];
         try {
             if (Is.arrayValue(conditions)) {
                 const itemData = await this.get(id);
@@ -260,30 +301,21 @@ export class PostgreSqlEntityStorageConnector {
                     return;
                 }
             }
-            const finalEntity = ObjectHelper.clone(entity);
             const props = [...(this._entitySchema.properties ?? [])];
             props.unshift({
                 property: PostgreSqlEntityStorageConnector._PARTITION_KEY,
                 type: EntitySchemaPropertyType.String
             });
-            ObjectHelper.propertySet(finalEntity, PostgreSqlEntityStorageConnector._PARTITION_KEY, partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE);
-            ObjectHelper.propertySet(finalEntity, PostgreSqlEntityStorageConnector._PARTITION_KEY, partitionKey ?? PostgreSqlEntityStorageConnector._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 (finalEntity[prop.property] === undefined) {
-                        values.push(null);
-                    }
-                    else {
-                        values.push(finalEntity[prop.property]);
-                    }
-                }
+                keys.push(prop.property);
+                const val = prepared[prop.property];
+                values.push(val ?? null);
             }
             let sql = `INSERT INTO "${this._config.tableName}"`;
             sql += ` (${keys.map(key => `"${key}"`).join(", ")})`;
-            sql += ` VALUES (${values.map((_, i) => `$${i + 1}`).join(", ")})`;
+            sql += ` VALUES (${values.map((value, i) => `$${i + 1}`).join(", ")})`;
             sql += ` ON CONFLICT ("${PostgreSqlEntityStorageConnector._PARTITION_KEY}", "${this._primaryKeyProperty.property}")`;
             sql += ` DO UPDATE SET ${keys.map(key => `"${key}" = EXCLUDED."${key}"`).join(", ")};`;
             const dbConnection = await this.createConnection();
@@ -295,6 +327,69 @@ export class PostgreSqlEntityStorageConnector {
             }, err);
         }
     }
+    /**
+     * Set multiple entities in a batch.
+     * @param entities The entities to set.
+     * @returns Nothing.
+     */
+    async setBatch(entities) {
+        Guards.arrayValue(PostgreSqlEntityStorageConnector.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: PostgreSqlEntityStorageConnector._PARTITION_KEY,
+                value: partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE
+            }
+        ], { nullBehavior: "nullify" }));
+        try {
+            const props = [...(this._entitySchema.properties ?? [])];
+            props.unshift({
+                property: PostgreSqlEntityStorageConnector._PARTITION_KEY,
+                type: EntitySchemaPropertyType.String
+            });
+            const keys = props.map(p => p.property);
+            const allValues = [];
+            const rowPlaceholders = [];
+            for (const prepared of preparedEntities) {
+                const rowValues = [];
+                for (const prop of props) {
+                    const val = prepared[prop.property];
+                    allValues.push(Is.empty(val) ? null : val);
+                    rowValues.push(`$${allValues.length}`);
+                }
+                rowPlaceholders.push(`(${rowValues.join(", ")})`);
+            }
+            let sql = `INSERT INTO "${this._config.tableName}"`;
+            sql += ` (${keys.map(key => `"${key}"`).join(", ")})`;
+            sql += ` VALUES ${rowPlaceholders.join(", ")}`;
+            sql += ` ON CONFLICT ("${PostgreSqlEntityStorageConnector._PARTITION_KEY}", "${this._primaryKeyProperty.property}")`;
+            sql += ` DO UPDATE SET ${keys.map(key => `"${key}" = EXCLUDED."${key}"`).join(", ")};`;
+            const dbConnection = await this.createConnection();
+            await dbConnection.unsafe(sql, allValues);
+        }
+        catch (err) {
+            throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "setBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Empty all the entities.
+     * @returns Nothing.
+     */
+    async empty() {
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const sql = `DELETE FROM "${this._config.tableName}" WHERE "${PostgreSqlEntityStorageConnector._PARTITION_KEY}" = $1`;
+            const dbConnection = await this.createConnection();
+            await dbConnection.unsafe(sql, [
+                partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE
+            ]);
+        }
+        catch (err) {
+            throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "emptyFailed", undefined, err);
+        }
+    }
     /**
      * Remove the entity.
      * @param id The id of the entity to remove.
@@ -331,6 +426,136 @@ export class PostgreSqlEntityStorageConnector {
             }, err);
         }
     }
+    /**
+     * Remove multiple entities by their primary key IDs.
+     * @param ids The ids of the entities to remove.
+     * @returns Nothing.
+     */
+    async removeBatch(ids) {
+        Guards.arrayValue(PostgreSqlEntityStorageConnector.CLASS_NAME, "ids", ids);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const sql = `DELETE FROM "${this._config.tableName}" WHERE "${PostgreSqlEntityStorageConnector._PARTITION_KEY}" = $1 AND "${this._primaryKeyProperty.property}" = ANY($2)`;
+            const dbConnection = await this.createConnection();
+            await dbConnection.unsafe(sql, [
+                partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE,
+                ids
+            ]);
+        }
+        catch (err) {
+            throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "removeBatchFailed", undefined, 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: PostgreSqlEntityStorageConnector.CLASS_NAME,
+            ts: Date.now(),
+            message: "tableDropping",
+            data: { tableName: this._config.tableName }
+        });
+        try {
+            const tableExists = await this.tableExists();
+            if (tableExists) {
+                const dbConnection = await this.createConnection();
+                await dbConnection.unsafe(`DROP TABLE "${this._config.tableName}";`);
+                await this.waitForTableNotExists();
+            }
+            await nodeLogging?.log({
+                level: "info",
+                source: PostgreSqlEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "tableDropped",
+                data: { tableName: this._config.tableName }
+            });
+            return true;
+        }
+        catch (err) {
+            await nodeLogging?.log({
+                level: "error",
+                source: PostgreSqlEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "teardownFailed",
+                error: BaseError.fromError(err)
+            });
+            return false;
+        }
+    }
+    /**
+     * Get all the distinct partition context ids from the storage.
+     * @returns An array of context id objects, one per unique partition.
+     */
+    async getPartitionContextIds() {
+        if (!Is.arrayValue(this._partitionContextIds)) {
+            return [];
+        }
+        try {
+            const dbConnection = await this.createConnection();
+            const rows = await dbConnection.unsafe(`SELECT DISTINCT "${PostgreSqlEntityStorageConnector._PARTITION_KEY}" FROM "${this._config.tableName}"`);
+            return rows
+                .map(row => row[PostgreSqlEntityStorageConnector._PARTITION_KEY])
+                .filter((id) => Is.stringValue(id))
+                .map(id => ContextIdHelper.shortSplit(this._partitionContextIds ?? [], id));
+        }
+        catch (err) {
+            throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "getPartitionContextIdsFailed", undefined, err);
+        }
+    }
+    /**
+     * Create a new target connector for the migration.
+     * @param entitySchemaName The entity schema name to use for the target connector.
+     * @returns A new connector configured with a migration table name.
+     */
+    async createTargetConnector(entitySchemaName) {
+        return new PostgreSqlEntityStorageConnector({
+            entitySchema: entitySchemaName,
+            config: {
+                ...this._config,
+                tableName: `${this._config.tableName}Migration${Date.now()}`
+            },
+            partitionContextIds: this._partitionContextIds
+        });
+    }
+    /**
+     * Finalize the migration by renaming the migration table to the original table name.
+     * @param targetConnector The connector pointing to the migration table.
+     * @param options The optional migration options.
+     * @param loggingComponentType The node logging component type.
+     * @returns A connector pointing to the final (renamed) table.
+     */
+    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);
+        const dbConnection = await targetConnector.createConnection();
+        await dbConnection.unsafe(`ALTER TABLE "${targetConnector._config.tableName}" RENAME TO "${this._config.tableName}"`);
+        const finalConnector = new PostgreSqlEntityStorageConnector({
+            entitySchema: targetConnector._entitySchemaName,
+            config: this._config,
+            partitionContextIds: this._partitionContextIds
+        });
+        if (await finalConnector.bootstrap(loggingComponentType)) {
+            await targetConnector.stop();
+            return finalConnector;
+        }
+        throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "finalizeMigrationFailedBootstrap", undefined);
+    }
+    /**
+     * Clean up the migration by tearing down the migration table.
+     * @param targetConnector The connector pointing to the migration table.
+     * @param options The optional migration options.
+     * @param loggingComponentType The node logging component type.
+     */
+    async cleanupMigration(targetConnector, options, loggingComponentType) {
+        // If something failed the only thing to cleanup is the migration table
+        await targetConnector?.teardown?.(loggingComponentType);
+    }
     /**
      * Find all the entities which match the conditions.
      * @param conditions The conditions to match for the entities.
@@ -344,6 +569,13 @@ export class PostgreSqlEntityStorageConnector {
     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(PostgreSqlEntityStorageConnector.CLASS_NAME, "query", validationFailures);
+        }
         let sql = "";
         try {
             const returnSize = limit ?? PostgreSqlEntityStorageConnector._DEFAULT_LIMIT;
@@ -356,25 +588,13 @@ export class PostgreSqlEntityStorageConnector {
                 }
                 orderByClause = `ORDER BY ${orderClauses.join(", ")}`;
             }
-            const whereClauses = [];
-            const values = [];
-            const finalConditions = {
-                conditions: [],
-                logicalOperator: LogicalOperator.And
-            };
-            finalConditions.conditions.push({
-                property: PostgreSqlEntityStorageConnector._PARTITION_KEY,
-                comparison: ComparisonOperator.Equals,
-                value: partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE
-            });
-            if (!Is.empty(conditions)) {
-                finalConditions.conditions.push(conditions);
-            }
-            this.buildQueryParameters("", finalConditions, whereClauses, values, 1);
+            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.tableName}"`;
-            sql += ` WHERE ${whereClauses.join(" AND ")}`;
-            sql += ` ${orderByClause} LIMIT ${returnSize} OFFSET ${startIndex}`;
+            if (whereClauses.length > 0) {
+                sql += ` WHERE ${whereClauses.join(" AND ")}`;
+            }
+            sql += ` ${orderByClause} LIMIT ${returnSize + 1} OFFSET ${startIndex}`;
             const dbConnection = await this.createConnection();
             const rows = await dbConnection.unsafe(sql, values);
             if (this._entitySchema.properties) {
@@ -403,16 +623,17 @@ export class PostgreSqlEntityStorageConnector {
                     }
                 }
             }
-            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++) {
-                ObjectHelper.propertyDelete(entities[i], PostgreSqlEntityStorageConnector._PARTITION_KEY);
-                entities[i] = ObjectHelper.removeEmptyProperties(entities[i], { removeNull: true });
+                entities[i] = EntityStorageHelper.unPrepareEntity(entities[i], [
+                    PostgreSqlEntityStorageConnector._PARTITION_KEY
+                ]);
             }
             return {
                 entities,
-                cursor: Is.array(rows) && rows.length === returnSize
-                    ? Coerce.string(startIndex + returnSize)
-                    : undefined
+                cursor: hasMore ? Coerce.string(startIndex + returnSize) : undefined
             };
         }
         catch (err) {
@@ -420,21 +641,26 @@ export class PostgreSqlEntityStorageConnector {
         }
     }
     /**
-     * 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 queryStr;
         try {
-            const tableExists = await this.tableExists();
-            if (!tableExists) {
-                return;
-            }
             const dbConnection = await this.createConnection();
-            await dbConnection.unsafe(`DROP TABLE "${this._config.tableName}";`);
-            await this.waitForTableNotExists();
+            const contextIds = await ContextIdStore.getContextIds();
+            const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+            const { whereClauses, values } = this.buildWhereClause(conditions, partitionKey);
+            queryStr = `SELECT COUNT(*) AS count FROM "${this._config.tableName}"`;
+            if (whereClauses.length > 0) {
+                queryStr += ` WHERE ${whereClauses.join(" AND ")}`;
+            }
+            const result = await dbConnection.unsafe(queryStr, values);
+            return Number(result[0].count);
         }
-        catch {
-            // Ignore errors
+        catch (err) {
+            throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "countFailed", { sql: queryStr }, err);
         }
     }
     /**
@@ -474,9 +700,8 @@ export class PostgreSqlEntityStorageConnector {
     async tableExists() {
         try {
             const dbConnection = await this.createConnection();
-            const tableExistsQuery = `SELECT to_regclass('${this._config.tableName}')`;
-            const tableExistsResult = await dbConnection.unsafe(tableExistsQuery);
-            return tableExistsResult[0].to_regclass !== null;
+            const res = await dbConnection.unsafe("SELECT 1 FROM information_schema.tables WHERE table_schema = 'public' AND table_name = $1 LIMIT 1", [this._config.tableName]);
+            return res.length > 0;
         }
         catch {
             return false;
@@ -534,6 +759,31 @@ export class PostgreSqlEntityStorageConnector {
             password: this._config.password
         };
     }
+    /**
+     * 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: PostgreSqlEntityStorageConnector._PARTITION_KEY,
+            comparison: ComparisonOperator.Equals,
+            value: partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE
+        });
+        if (!Is.empty(conditions)) {
+            finalConditions.conditions.push(conditions);
+        }
+        this.buildQueryParameters("", finalConditions, whereClauses, values, 1);
+        return { whereClauses, values };
+    }
     /**
      * Create an SQL condition clause.
      * @param objectPath The path for the nested object.
@@ -589,8 +839,13 @@ export class PostgreSqlEntityStorageConnector {
         prop += comparator.property;
         if (comparator.comparison === ComparisonOperator.In) {
             const inValues = Is.array(comparator.value) ? comparator.value : [comparator.value];
+            if (inValues.length === 0) {
+                // PostgreSQL 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((_, index) => `$${valueIndex + index}`).join(", ");
+            const placeholders = inValues.map((value, index) => `$${valueIndex + index}`).join(", ");
             return `"${prop}" IN (${placeholders})`;
         }
         // null/undefined must use IS NULL / IS NOT NULL — never a parameterised placeholder.
@@ -636,6 +891,17 @@ export class PostgreSqlEntityStorageConnector {
                     }
                     return `LOWER(${jsonTextExpr}) ILIKE $${valueIndex}`;
                 }
+                case ComparisonOperator.NotIncludes: {
+                    values.pop();
+                    values.push(`%${String(comparator.value).toLowerCase()}%`);
+                    if (isArray) {
+                        const elemPath = nestedParts
+                            .map((p, i, arr) => (i === arr.length - 1 ? `->>'${p}'` : `->'${p}'`))
+                            .join("");
+                        return `NOT EXISTS (SELECT 1 FROM jsonb_array_elements("${rootProp}") elem WHERE LOWER(elem${elemPath}) ILIKE $${valueIndex})`;
+                    }
+                    return `LOWER(${jsonTextExpr}) NOT ILIKE $${valueIndex}`;
+                }
                 case ComparisonOperator.NotEquals:
                     return `${jsonTextExpr} <> $${valueIndex}`;
                 case ComparisonOperator.GreaterThan:
@@ -681,6 +947,18 @@ export class PostgreSqlEntityStorageConnector {
                     type
                 });
             }
+            case ComparisonOperator.NotIncludes: {
+                if (type === EntitySchemaPropertyType.String) {
+                    return `"${prop}" NOT ILIKE '%' || $${valueIndex} || '%'`;
+                }
+                if (type === EntitySchemaPropertyType.Array || type === EntitySchemaPropertyType.Object) {
+                    return `NOT EXISTS (SELECT 1 FROM jsonb_array_elements("${prop}") elem WHERE elem @> $${valueIndex}::jsonb)`;
+                }
+                throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "comparisonNotSupported", {
+                    comparison: comparator.comparison,
+                    type
+                });
+            }
             default:
                 throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "comparisonNotSupported", {
                     comparison: comparator.comparison
@@ -731,6 +1009,8 @@ export class PostgreSqlEntityStorageConnector {
     /**
      * 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) {
@@ -741,6 +1021,7 @@ export class PostgreSqlEntityStorageConnector {
      * @param entitySchema The schema of the entity.
      * @returns The SQL properties as a string.
      * @throws GeneralError if the entity properties do not exist.
+     * @internal
      */
     mapPostgreSqlProperties(entitySchema) {
         const sqlTypeMap = {