@twin.org/entity-storage-connector-postgresql 0.9.2-next.1 → 0.9.2-next.10

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

@@ -1 +1 @@
-{"version":3,"file":"IPostgreSqlEntityStorageConnectorConfig.js","sourceRoot":"","sources":["../../../src/models/IPostgreSqlEntityStorageConnectorConfig.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 PostgreSql Entity Storage Connector.\n */\nexport interface IPostgreSqlEntityStorageConnectorConfig {\n\t/**\n\t * The host for the PostgreSql instance.\n\t */\n\thost: string;\n\n\t/**\n\t * The port for the PostgreSql instance.\n\t */\n\tport?: number;\n\n\t/**\n\t * The user for the PostgreSql instance.\n\t */\n\tuser: string;\n\n\t/**\n\t * The password for the PostgreSql 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":"IPostgreSqlEntityStorageConnectorConfig.js","sourceRoot":"","sources":["../../../src/models/IPostgreSqlEntityStorageConnectorConfig.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 PostgreSql Entity Storage Connector.\n */\nexport interface IPostgreSqlEntityStorageConnectorConfig {\n\t/**\n\t * The host for the PostgreSql instance.\n\t */\n\thost: string;\n\n\t/**\n\t * The port for the PostgreSql instance.\n\t */\n\tport?: number;\n\n\t/**\n\t * The user for the PostgreSql instance.\n\t */\n\tuser: string;\n\n\t/**\n\t * The password for the PostgreSql 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 the pool.\n\t\t * @default 10\n\t\t */\n\t\tmax?: number;\n\n\t\t/**\n\t\t * Seconds a connection can remain idle before being closed.\n\t\t */\n\t\tidleTimeout?: number;\n\n\t\t/**\n\t\t * Seconds to wait when establishing a connection.\n\t\t * @default 30\n\t\t */\n\t\tconnectTimeout?: number;\n\n\t\t/**\n\t\t * Maximum seconds a connection can remain open.\n\t\t */\n\t\tmaxLifetime?: number;\n\t};\n\n\t/**\n\t * Milliseconds to wait for connector mutex locks before throwing.\n\t */\n\tmutexTimeoutMs?: number;\n}\n"]}

package/dist/es/postgreSqlEntityStorageConnector.js

@@ -1,9 +1,10 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
+import { HealthCategory, HealthStatus } from "@twin.org/api-models";
 import { ContextIdHelper, ContextIdStore } from "@twin.org/context";
-import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, HealthStatus, Is, ObjectHelper, Validation } from "@twin.org/core";
+import { BaseError, Coerce, ComponentFactory, ConflictError, Converter, GeneralError, Guards, Is, Mutex, ObjectHelper, RandomHelper, 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 { ConnectionHelper, EntityStorageHelper, IndexHelper } from "@twin.org/entity-storage-models";
 import postgres from "postgres";
 /**
  * Class for performing entity storage operations using ql.
@@ -28,6 +29,11 @@ export class PostgreSqlEntityStorageConnector {
      * @internal
      */
     static _PARTITION_KEY_VALUE = "root";
+    /**
+     * Maximum number of rows per INSERT statement in setBatch.
+     * @internal
+     */
+    static _BATCH_CHUNK_SIZE = 1000;
     /**
      * The name for the schema.
      * @internal
@@ -48,16 +54,26 @@ export class PostgreSqlEntityStorageConnector {
      * @internal
      */
     _primaryKeyProperty;
+    /**
+     * The name of the version property, if any.
+     * @internal
+     */
+    _versionKey;
     /**
      * The configuration for the connector.
      * @internal
      */
     _config;
     /**
-     * The configuration for the connector.
+     * Milliseconds to wait for optimistic-lock mutexes before throwing.
      * @internal
      */
-    _connection;
+    _mutexTimeoutMs;
+    /**
+     * Unique identifier for this connector instance, used to track references in SharedStore.
+     * @internal
+     */
+    _instanceId;
     /**
      * Create a new instance of PostgreSqlEntityStorageConnector.
      * @param options The options for the connector.
@@ -71,11 +87,26 @@ 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);
+        if (!Is.empty(options.config.pool?.connectTimeout)) {
+            Guards.integer(PostgreSqlEntityStorageConnector.CLASS_NAME, "options.config.pool.connectTimeout", options.config.pool?.connectTimeout);
+        }
+        if (!Is.empty(options.config.pool?.idleTimeout)) {
+            Guards.integer(PostgreSqlEntityStorageConnector.CLASS_NAME, "options.config.pool.idleTimeout", options.config.pool?.idleTimeout);
+        }
+        if (!Is.empty(options.config.pool?.max)) {
+            Guards.integer(PostgreSqlEntityStorageConnector.CLASS_NAME, "options.config.pool.max", options.config.pool?.max);
+        }
+        if (!Is.empty(options.config.pool?.maxLifetime)) {
+            Guards.integer(PostgreSqlEntityStorageConnector.CLASS_NAME, "options.config.pool.maxLifetime", options.config.pool?.maxLifetime);
+        }
         this._entitySchemaName = options.entitySchema;
         this._entitySchema = EntitySchemaFactory.get(options.entitySchema);
         this._partitionContextIds = options.partitionContextIds;
         this._primaryKeyProperty = EntitySchemaHelper.getPrimaryKey(this._entitySchema);
+        this._versionKey = EntitySchemaHelper.findVersionProperty(this._entitySchema);
         this._config = options.config;
+        this._mutexTimeoutMs = Coerce.integer(options.config.mutexTimeoutMs);
+        this._instanceId = RandomHelper.generateUuidV7("compact");
     }
     /**
      * Initialize the PostgreSql environment.
@@ -85,7 +116,7 @@ export class PostgreSqlEntityStorageConnector {
     async bootstrap(nodeLoggingComponentType) {
         const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
         try {
-            const dbConnection = await this.createConnection();
+            const dbConnection = await this.getClient();
             const databaseExists = await this.databaseExists();
             if (!databaseExists) {
                 await nodeLogging?.log({
@@ -137,6 +168,15 @@ export class PostgreSqlEntityStorageConnector {
                     }
                 });
             }
+            for (const prop of this._entitySchema.properties ?? []) {
+                if ((prop.isSecondary === true || !Is.empty(prop.sortDirection)) &&
+                    prop.type !== EntitySchemaPropertyType.Object &&
+                    prop.type !== EntitySchemaPropertyType.Array) {
+                    const columnName = String(prop.property);
+                    const indexName = IndexHelper.generateName(this._config.tableName, columnName);
+                    await dbConnection.unsafe(`CREATE INDEX IF NOT EXISTS "${indexName}" ON "${this._config.tableName}" ("${columnName}")`);
+                }
+            }
         }
         catch (error) {
             await nodeLogging?.log({
@@ -161,16 +201,17 @@ export class PostgreSqlEntityStorageConnector {
         return PostgreSqlEntityStorageConnector.CLASS_NAME;
     }
     /**
-     * Get the health of the component.
-     * @returns The health of the component.
+     * Returns the health status of the component.
+     * @returns The health status of the component.
      */
     async health() {
         try {
-            const sql = await this.createConnection();
+            const sql = await this.getClient();
             await sql `SELECT 1 FROM ${sql(this._config.tableName)} LIMIT 0`;
             return [
                 {
                     source: PostgreSqlEntityStorageConnector.CLASS_NAME,
+                    category: HealthCategory.Connectivity,
                     status: HealthStatus.Ok,
                     description: "healthDescription",
                     data: { tableName: this._config.tableName }
@@ -181,6 +222,7 @@ export class PostgreSqlEntityStorageConnector {
             return [
                 {
                     source: PostgreSqlEntityStorageConnector.CLASS_NAME,
+                    category: HealthCategory.Connectivity,
                     status: HealthStatus.Error,
                     description: "healthDescription",
                     message: "connectionFailed",
@@ -194,10 +236,7 @@ export class PostgreSqlEntityStorageConnector {
      * @returns Nothing.
      */
     async stop() {
-        if (this._connection) {
-            await this._connection.end();
-            this._connection = undefined;
-        }
+        await ConnectionHelper.closeClient("postgreSqlConnections", `${this._config.host}|${this._config.port ?? 5432}|${this._config.user}`, this._instanceId, this._mutexTimeoutMs, async (sql) => sql.end());
     }
     /**
      * Get the schema for the entities.
@@ -219,7 +258,7 @@ export class PostgreSqlEntityStorageConnector {
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
         try {
-            const dbConnection = await this.createConnection();
+            const dbConnection = await this.getClient();
             const whereClauses = [];
             const values = [];
             whereClauses.push(`"${PostgreSqlEntityStorageConnector._PARTITION_KEY}" = $1`);
@@ -283,12 +322,17 @@ export class PostgreSqlEntityStorageConnector {
      * @param entity The entity to set.
      * @param conditions The optional conditions to match for the entities.
      * @returns The id of the entity.
+     * @throws ConflictError when the entity exists but the supplied conditions or version do not match the stored state.
      */
     async set(entity, conditions) {
         Guards.object(PostgreSqlEntityStorageConnector.CLASS_NAME, "entity", entity);
         EntityStorageHelper.validateConditions(this._entitySchema, conditions);
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const submittedVersion = Is.stringValue(this._versionKey)
+            ? Coerce.integer(ObjectHelper.propertyGet(entity, this._versionKey))
+            : undefined;
+        const hasVersionCheck = !Is.empty(this._versionKey) && !Is.empty(submittedVersion) && submittedVersion > 0;
         const prepared = EntityStorageHelper.prepareEntity(entity, this._entitySchema, [
             {
                 property: PostgreSqlEntityStorageConnector._PARTITION_KEY,
@@ -296,11 +340,40 @@ export class PostgreSqlEntityStorageConnector {
             }
         ], { nullBehavior: "nullify" });
         const id = prepared[this._primaryKeyProperty.property];
+        const optimisticMutexKey = Is.stringValue(this._versionKey)
+            ? this.buildOptimisticMutexKey(partitionKey, id)
+            : undefined;
+        if (Is.stringValue(optimisticMutexKey)) {
+            await Mutex.lock(optimisticMutexKey, {
+                throwOnTimeout: true,
+                timeoutMs: this._mutexTimeoutMs
+            });
+        }
         try {
-            if (Is.arrayValue(conditions)) {
-                const itemData = await this.get(id);
-                if (Is.notEmpty(itemData) && !this.verifyConditions(conditions, itemData)) {
-                    return;
+            if (hasVersionCheck) {
+                if (Is.arrayValue(conditions)) {
+                    const currentEntity = await this.get(id);
+                    if (!Is.empty(currentEntity) && !this.verifyConditions(conditions, currentEntity)) {
+                        throw new ConflictError(PostgreSqlEntityStorageConnector.CLASS_NAME, "conditionFailed", id);
+                    }
+                }
+                ObjectHelper.propertySet(prepared, this._versionKey, submittedVersion + 1);
+            }
+            else if (this._versionKey || Is.arrayValue(conditions)) {
+                const currentEntity = await this.get(id);
+                if (!Is.empty(currentEntity)) {
+                    if (Is.arrayValue(conditions) && !this.verifyConditions(conditions, currentEntity)) {
+                        if (Is.stringValue(this._versionKey)) {
+                            throw new ConflictError(PostgreSqlEntityStorageConnector.CLASS_NAME, "conditionFailed", id);
+                        }
+                        return;
+                    }
+                }
+                if (Is.stringValue(this._versionKey)) {
+                    const storedVersion = Coerce.integer(!Is.empty(currentEntity)
+                        ? ObjectHelper.propertyGet(currentEntity, this._versionKey)
+                        : 0) ?? 0;
+                    ObjectHelper.propertySet(prepared, this._versionKey, storedVersion + 1);
                 }
             }
             const props = [...(this._entitySchema.properties ?? [])];
@@ -319,15 +392,33 @@ export class PostgreSqlEntityStorageConnector {
             sql += ` (${keys.map(key => `"${key}"`).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();
-            await dbConnection.unsafe(sql, values);
+            if (hasVersionCheck) {
+                sql += ` DO UPDATE SET ${keys.map(key => `"${key}" = EXCLUDED."${key}"`).join(", ")}`;
+                sql += ` WHERE "${this._config.tableName}"."${this._versionKey}" = $${values.length + 1}`;
+                values.push(submittedVersion);
+            }
+            else {
+                sql += ` DO UPDATE SET ${keys.map(key => `"${key}" = EXCLUDED."${key}"`).join(", ")};`;
+            }
+            const dbConnection = await this.getClient();
+            const result = await dbConnection.unsafe(sql, values);
+            if (hasVersionCheck && result.count === 0) {
+                throw new ConflictError(PostgreSqlEntityStorageConnector.CLASS_NAME, "optimisticLockFailed", id);
+            }
         }
         catch (err) {
+            if (BaseError.isErrorName(err, ConflictError.CLASS_NAME)) {
+                throw err;
+            }
             throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "setFailed", {
                 id
             }, err);
         }
+        finally {
+            if (Is.stringValue(optimisticMutexKey)) {
+                Mutex.unlock(optimisticMutexKey);
+            }
+        }
     }
     /**
      * Set multiple entities in a batch.
@@ -351,24 +442,28 @@ export class PostgreSqlEntityStorageConnector {
                 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}`);
+            const dbConnection = await this.getClient();
+            const chunkSize = PostgreSqlEntityStorageConnector._BATCH_CHUNK_SIZE;
+            for (let offset = 0; offset < preparedEntities.length; offset += chunkSize) {
+                const chunk = preparedEntities.slice(offset, offset + chunkSize);
+                const allValues = [];
+                const rowPlaceholders = [];
+                for (const prepared of chunk) {
+                    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(", ")})`);
                 }
-                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(", ")};`;
+                await dbConnection.unsafe(sql, allValues);
             }
-            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);
@@ -383,7 +478,7 @@ export class PostgreSqlEntityStorageConnector {
         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();
+            const dbConnection = await this.getClient();
             await dbConnection.unsafe(sql, [
                 partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE
             ]);
@@ -403,10 +498,25 @@ export class PostgreSqlEntityStorageConnector {
         EntityStorageHelper.validateConditions(this._entitySchema, conditions);
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const optimisticMutexKey = Is.stringValue(this._versionKey)
+            ? this.buildOptimisticMutexKey(partitionKey, id)
+            : undefined;
+        if (Is.stringValue(optimisticMutexKey)) {
+            await Mutex.lock(optimisticMutexKey, {
+                throwOnTimeout: true,
+                timeoutMs: this._mutexTimeoutMs
+            });
+        }
         try {
-            const dbConnection = await this.createConnection();
+            const dbConnection = await this.getClient();
             const itemData = await this.get(id);
-            if (Is.notEmpty(itemData)) {
+            if (!Is.empty(itemData)) {
+                if (Is.arrayValue(conditions) && !this.verifyConditions(conditions, itemData)) {
+                    if (Is.stringValue(this._versionKey)) {
+                        throw new ConflictError(PostgreSqlEntityStorageConnector.CLASS_NAME, "conditionFailed", id);
+                    }
+                    return;
+                }
                 const values = [];
                 const whereClauses = [];
                 whereClauses.push(`"${this._primaryKeyProperty.property}" = $${values.length + 1}`);
@@ -424,10 +534,18 @@ export class PostgreSqlEntityStorageConnector {
             }
         }
         catch (err) {
+            if (BaseError.isErrorName(err, ConflictError.CLASS_NAME)) {
+                throw err;
+            }
             throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "removeFailed", {
                 id
             }, err);
         }
+        finally {
+            if (Is.stringValue(optimisticMutexKey)) {
+                Mutex.unlock(optimisticMutexKey);
+            }
+        }
     }
     /**
      * Remove multiple entities by their primary key IDs.
@@ -440,7 +558,7 @@ export class PostgreSqlEntityStorageConnector {
         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();
+            const dbConnection = await this.getClient();
             await dbConnection.unsafe(sql, [
                 partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE,
                 ids
@@ -467,7 +585,7 @@ export class PostgreSqlEntityStorageConnector {
         try {
             const tableExists = await this.tableExists();
             if (tableExists) {
-                const dbConnection = await this.createConnection();
+                const dbConnection = await this.getClient();
                 await dbConnection.unsafe(`DROP TABLE "${this._config.tableName}";`);
                 await this.waitForTableNotExists();
             }
@@ -491,6 +609,13 @@ export class PostgreSqlEntityStorageConnector {
             return false;
         }
     }
+    /**
+     * Get the connector implementation version.
+     * @returns The connector implementation version.
+     */
+    connectorVersion() {
+        return 0;
+    }
     /**
      * Get all the distinct partition context ids from the storage.
      * @returns An array of context id objects, one per unique partition.
@@ -500,7 +625,7 @@ export class PostgreSqlEntityStorageConnector {
             return undefined;
         }
         try {
-            const dbConnection = await this.createConnection();
+            const dbConnection = await this.getClient();
             const rows = await dbConnection.unsafe(`SELECT DISTINCT "${PostgreSqlEntityStorageConnector._PARTITION_KEY}" FROM "${this._config.tableName}"`);
             return rows
                 .map(row => row[PostgreSqlEntityStorageConnector._PARTITION_KEY])
@@ -536,7 +661,7 @@ export class PostgreSqlEntityStorageConnector {
     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();
+        const dbConnection = await targetConnector.getClient();
         await dbConnection.unsafe(`ALTER TABLE "${targetConnector._config.tableName}" RENAME TO "${this._config.tableName}"`);
         const finalConnector = new PostgreSqlEntityStorageConnector({
             entitySchema: targetConnector._entitySchemaName,
@@ -583,23 +708,61 @@ export class PostgreSqlEntityStorageConnector {
         let sql = "";
         try {
             const returnSize = limit ?? PostgreSqlEntityStorageConnector._DEFAULT_LIMIT;
-            let orderByClause = "";
-            if (Is.arrayValue(sortProperties)) {
-                const orderClauses = [];
-                for (const sortProperty of sortProperties) {
-                    const direction = sortProperty.sortDirection === SortDirection.Ascending ? "ASC" : "DESC";
-                    orderClauses.push(`"${String(sortProperty.property)}" ${direction}`);
+            const pkPropName = String(this._primaryKeyProperty.property);
+            const sortsByPK = Is.array(sortProperties) && sortProperties.some(s => String(s.property) === pkPropName);
+            const keySetCols = [];
+            if (Is.array(sortProperties)) {
+                for (const s of sortProperties) {
+                    keySetCols.push({
+                        prop: String(s.property),
+                        asc: s.sortDirection === SortDirection.Ascending
+                    });
                 }
-                orderByClause = `ORDER BY ${orderClauses.join(", ")}`;
             }
+            if (!sortsByPK) {
+                keySetCols.push({ prop: pkPropName, asc: true });
+            }
+            const requestedProps = properties ? new Set(properties.map(p => String(p))) : undefined;
+            const internallyAdded = new Set();
+            let selectClause;
+            if (requestedProps) {
+                const selectSet = new Set(requestedProps);
+                for (const col of keySetCols) {
+                    if (!selectSet.has(col.prop)) {
+                        selectSet.add(col.prop);
+                        internallyAdded.add(col.prop);
+                    }
+                }
+                selectClause = [...selectSet].map(p => `"${p}"`).join(", ");
+            }
+            else {
+                selectClause = "*";
+            }
+            const orderByClause = `ORDER BY ${keySetCols.map(c => `"${c.prop}" ${c.asc ? "ASC" : "DESC"}`).join(", ")}`;
             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}"`;
+            if (Is.stringBase64(cursor)) {
+                const parsedCursor = ObjectHelper.fromBytes(Converter.base64ToBytes(cursor));
+                const lastValues = [...(parsedCursor.sv ?? []), parsedCursor.i];
+                const orParts = [];
+                for (let i = 0; i < keySetCols.length; i++) {
+                    const parts = [];
+                    for (let j = 0; j < i; j++) {
+                        values.push(lastValues[j]);
+                        parts.push(`"${keySetCols[j].prop}" = $${values.length}`);
+                    }
+                    const op = keySetCols[i].asc ? ">" : "<";
+                    values.push(lastValues[i]);
+                    parts.push(`"${keySetCols[i].prop}" ${op} $${values.length}`);
+                    orParts.push(parts.length === 1 ? parts[0] : `(${parts.join(" AND ")})`);
+                }
+                whereClauses.push(`(${orParts.join(" OR ")})`);
+            }
+            sql = `SELECT ${selectClause} FROM "${this._config.tableName}"`;
             if (whereClauses.length > 0) {
                 sql += ` WHERE ${whereClauses.join(" AND ")}`;
             }
-            sql += ` ${orderByClause} LIMIT ${returnSize + 1} OFFSET ${startIndex}`;
-            const dbConnection = await this.createConnection();
+            sql += ` ${orderByClause} LIMIT ${returnSize + 1}`;
+            const dbConnection = await this.getClient();
             const rows = await dbConnection.unsafe(sql, values);
             if (this._entitySchema.properties) {
                 for (const row of rows) {
@@ -630,15 +793,27 @@ export class PostgreSqlEntityStorageConnector {
             const hasMore = Is.array(rows) && rows.length > returnSize;
             const resultRows = hasMore ? rows.slice(0, returnSize) : rows;
             const entities = resultRows;
+            let nextCursor;
+            if (hasMore && entities.length > 0) {
+                const lastRow = entities[entities.length - 1];
+                const sortValues = keySetCols
+                    .slice(0, -1)
+                    .map(c => ObjectHelper.propertyGet(lastRow, c.prop));
+                const lastId = ObjectHelper.propertyGet(lastRow, pkPropName);
+                if (Is.stringValue(lastId)) {
+                    const cursorData = sortValues.length > 0 ? { i: lastId, sv: sortValues } : { i: lastId };
+                    nextCursor = Converter.bytesToBase64(ObjectHelper.toBytes(cursorData));
+                }
+            }
             for (let i = 0; i < entities.length; i++) {
                 entities[i] = EntityStorageHelper.unPrepareEntity(entities[i], [
                     PostgreSqlEntityStorageConnector._PARTITION_KEY
                 ]);
+                for (const col of internallyAdded) {
+                    ObjectHelper.propertyDelete(entities[i], col);
+                }
             }
-            return {
-                entities,
-                cursor: hasMore ? Coerce.string(startIndex + returnSize) : undefined
-            };
+            return { entities, cursor: nextCursor };
         }
         catch (err) {
             throw new GeneralError(PostgreSqlEntityStorageConnector.CLASS_NAME, "queryFailed", { sql }, err);
@@ -653,7 +828,7 @@ export class PostgreSqlEntityStorageConnector {
         EntityStorageHelper.validateConditionProperties(this._entitySchema, conditions);
         let queryStr;
         try {
-            const dbConnection = await this.createConnection();
+            const dbConnection = await this.getClient();
             const contextIds = await ContextIdStore.getContextIds();
             const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
             const { whereClauses, values } = this.buildWhereClause(conditions, partitionKey);
@@ -675,7 +850,7 @@ export class PostgreSqlEntityStorageConnector {
      */
     async databaseExists() {
         try {
-            const dbConnection = await this.createConnection();
+            const dbConnection = await this.getClient();
             const res = await dbConnection.unsafe("SELECT datname FROM pg_catalog.pg_database WHERE datname = $1", [this._config.database]);
             return res.length > 0;
         }
@@ -704,7 +879,7 @@ export class PostgreSqlEntityStorageConnector {
      */
     async tableExists() {
         try {
-            const dbConnection = await this.createConnection();
+            const dbConnection = await this.getClient();
             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;
         }
@@ -741,15 +916,12 @@ export class PostgreSqlEntityStorageConnector {
         }
     }
     /**
-     * Create a new DB connection.
-     * @returns The PostgreSql connection.
+     * Retrieve (or lazily create) the shared postgres connection for this endpoint.
+     * @returns The shared connection.
      * @internal
      */
-    async createConnection() {
-        if (Is.empty(this._connection)) {
-            this._connection = postgres(this.createConnectionConfig());
-        }
-        return this._connection;
+    async getClient() {
+        return ConnectionHelper.openClient("postgreSqlConnections", `${this._config.host}|${this._config.port ?? 5432}|${this._config.user}`, this._instanceId, this._mutexTimeoutMs, async () => postgres(this.createConnectionConfig()));
     }
     /**
      * Create a new DB connection configuration.
@@ -757,12 +929,20 @@ export class PostgreSqlEntityStorageConnector {
      * @internal
      */
     createConnectionConfig() {
-        return {
+        const opts = {
             host: this._config.host,
             port: this._config.port ?? 5432,
             user: this._config.user,
-            password: this._config.password
+            password: this._config.password,
+            max: this._config?.pool?.max,
+            // eslint-disable-next-line camelcase
+            idle_timeout: this._config?.pool?.idleTimeout,
+            // eslint-disable-next-line camelcase
+            connect_timeout: this._config?.pool?.connectTimeout,
+            // eslint-disable-next-line camelcase
+            max_lifetime: this._config?.pool?.maxLifetime
         };
+        return opts;
     }
     /**
      * Build where clause arrays for a query, combining partition key and optional conditions.
@@ -845,7 +1025,7 @@ export class PostgreSqlEntityStorageConnector {
         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
+                // 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";
             }
@@ -853,7 +1033,7 @@ export class PostgreSqlEntityStorageConnector {
             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.
+        // 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.
@@ -1021,6 +1201,16 @@ export class PostgreSqlEntityStorageConnector {
     verifyConditions(conditions, obj) {
         return conditions.every(condition => ObjectHelper.propertyGet(obj, condition.property) === condition.value);
     }
+    /**
+     * Build a mutex key for optimistic-locking critical sections.
+     * @param partitionKey The resolved partition key.
+     * @param id The entity id.
+     * @returns The mutex key.
+     * @internal
+     */
+    buildOptimisticMutexKey(partitionKey, id) {
+        return `${PostgreSqlEntityStorageConnector.CLASS_NAME}:optimistic:${this._config.tableName}:${partitionKey ?? PostgreSqlEntityStorageConnector._PARTITION_KEY_VALUE}:${id}`;
+    }
     /**
      * Map entity schema properties to SQL properties.
      * @param entitySchema The schema of the entity.