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

package/dist/types/postgreSqlEntityStorageConnector.d.ts

@@ -1,7 +1,7 @@
 import { type IHealth, type IHealthProviderComponent } from "@twin.org/api-models";
 import { type IContextIds } from "@twin.org/context";
 import { type EntityCondition, type IEntitySchema, SortDirection } from "@twin.org/entity";
-import { type IEntityStorageMigrationConnector, type IMigrationOptions } from "@twin.org/entity-storage-models";
+import { type IEntityStorageConnector, type IEntityStorageJoinOptions, type IEntityStorageMigrationConnector, type IMigrationOptions } from "@twin.org/entity-storage-models";
 import type { IPostgreSqlEntityStorageConnectorConstructorOptions } from "./models/IPostgreSqlEntityStorageConnectorConstructorOptions.js";
 /**
  * Class for performing entity storage operations using ql.
@@ -115,7 +115,7 @@ export declare class PostgreSqlEntityStorageConnector<T = unknown> implements IE
      */
     createTargetConnector<U>(entitySchemaName: string): Promise<PostgreSqlEntityStorageConnector<U>>;
     /**
-     * Finalize the migration by renaming the migration table to the original table name.
+     * Finalize the migration by dropping the source table and renaming the migration table into its name in one transaction.
      * @param targetConnector The connector pointing to the migration table.
      * @param options The optional migration options.
      * @param loggingComponentType The node logging component type.
@@ -146,6 +146,27 @@ export declare class PostgreSqlEntityStorageConnector<T = unknown> implements IE
         entities: Partial<T>[];
         cursor?: string;
     }>;
+    /**
+     * Find all the entities which match the conditions, attaching to each one the entities from a
+     * second storage connector whose join property matches. The join behaves like a left join by
+     * default, a primary entity with no matches is still returned with an empty joined list, unless
+     * joinRequired asks for an inner join and those entities are left out altogether. Both connectors
+     * must be PostgreSQL connectors reading from the same database so the work can be done in a
+     * single statement.
+     * @param joinConnector The connector holding the entities to join to.
+     * @param joinOptions The properties to join on, the conditions, sort order, projection and
+     * paging for the primary entities, the optional grouping and group conditions, and the optional
+     * conditions, sort order and projection for the joined entities.
+     * @returns All the entities for the storage matching the conditions with their joined entities,
+     * and a cursor which can be used to request more entities.
+     * @throws GeneralError if the join connector does not read from the same server and database.
+     */
+    queryJoin<U>(joinConnector: IEntityStorageConnector<U>, joinOptions: IEntityStorageJoinOptions<T, U>): Promise<{
+        entities: (Partial<T> & {
+            joined: Partial<U>[];
+        })[];
+        cursor?: string;
+    }>;
     /**
      * Count all the entities which match the conditions.
      * @param conditions The optional conditions to match for the entities.

package/docs/changelog.md

@@ -1,5 +1,149 @@
 # Changelog
 
+## [0.10.1-next.10](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.9...entity-storage-connector-postgresql-v0.10.1-next.10) (2026-09-23)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-connector-postgresql:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.9 to 0.10.1-next.10
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.9 to 0.10.1-next.10
+
+## [0.10.1-next.9](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.8...entity-storage-connector-postgresql-v0.10.1-next.9) (2026-09-22)
+
+
+### Bug Fixes
+
+* swap the migrated table into place atomically and fail loudly after an interrupted finalize ([#300](https://github.com/iotaledger/twin-entity-storage/issues/300)) ([0a59fb4](https://github.com/iotaledger/twin-entity-storage/commit/0a59fb452bafee9acfb730c0a3a3779a58fd1f3d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.8 to 0.10.1-next.9
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.8 to 0.10.1-next.9
+
+## [0.10.1-next.8](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.7...entity-storage-connector-postgresql-v0.10.1-next.8) (2026-09-22)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-connector-postgresql:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.7 to 0.10.1-next.8
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.7 to 0.10.1-next.8
+
+## [0.10.1-next.7](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.6...entity-storage-connector-postgresql-v0.10.1-next.7) (2026-09-22)
+
+
+### Bug Fixes
+
+* project properties in common group join ([b90389d](https://github.com/iotaledger/twin-entity-storage/commit/b90389dd7df593b560faf2299e912c25a66bf6ee))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.6 to 0.10.1-next.7
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.6 to 0.10.1-next.7
+
+## [0.10.1-next.6](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.5...entity-storage-connector-postgresql-v0.10.1-next.6) (2026-09-21)
+
+
+### Features
+
+* join and group ([#295](https://github.com/iotaledger/twin-entity-storage/issues/295)) ([e0103b3](https://github.com/iotaledger/twin-entity-storage/commit/e0103b3af5d9d0d37d4f590c6f31993d2c7e6508))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.5 to 0.10.1-next.6
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.5 to 0.10.1-next.6
+
+## [0.10.1-next.5](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.4...entity-storage-connector-postgresql-v0.10.1-next.5) (2026-09-18)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-connector-postgresql:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.4 to 0.10.1-next.5
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.4 to 0.10.1-next.5
+
+## [0.10.1-next.4](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.3...entity-storage-connector-postgresql-v0.10.1-next.4) (2026-09-18)
+
+
+### Features
+
+* add StartsWith comparison operator to all connectors ([#282](https://github.com/iotaledger/twin-entity-storage/issues/282)) ([fbb0b4a](https://github.com/iotaledger/twin-entity-storage/commit/fbb0b4a1a3d3f8ba80e8371bd2ec3a75260b9dd3))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.3 to 0.10.1-next.4
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.3 to 0.10.1-next.4
+
+## [0.10.1-next.3](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.2...entity-storage-connector-postgresql-v0.10.1-next.3) (2026-09-18)
+
+
+### Features
+
+* index include partitionid ([#280](https://github.com/iotaledger/twin-entity-storage/issues/280)) ([26d36e1](https://github.com/iotaledger/twin-entity-storage/commit/26d36e1c40207feb03c797b0ab00b485a1ae5cda))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.2 to 0.10.1-next.3
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.2 to 0.10.1-next.3
+
+## [0.10.1-next.2](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.1...entity-storage-connector-postgresql-v0.10.1-next.2) (2026-09-17)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-connector-postgresql:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.1 to 0.10.1-next.2
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.1 to 0.10.1-next.2
+
 ## [0.10.1-next.1](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.0...entity-storage-connector-postgresql-v0.10.1-next.1) (2026-09-17)
 
 

package/docs/reference/classes/PostgreSqlEntityStorageConnector.md

@@ -423,7 +423,7 @@ A new connector configured with a migration table name.
 
 > **finalizeMigration**\<`U`\>(`targetConnector`, `options?`, `loggingComponentType?`): `Promise`\<`PostgreSqlEntityStorageConnector`\<`U`\>\>
 
-Finalize the migration by renaming the migration table to the original table name.
+Finalize the migration by dropping the source table and renaming the migration table into its name in one transaction.
 
 #### Type Parameters
 
@@ -556,6 +556,56 @@ and a cursor which can be used to request more entities.
 
 ***
 
+### queryJoin() {#queryjoin}
+
+> **queryJoin**\<`U`\>(`joinConnector`, `joinOptions`): `Promise`\<\{ `entities`: `Partial`\<`T`\> & `object`[]; `cursor?`: `string`; \}\>
+
+Find all the entities which match the conditions, attaching to each one the entities from a
+second storage connector whose join property matches. The join behaves like a left join by
+default, a primary entity with no matches is still returned with an empty joined list, unless
+joinRequired asks for an inner join and those entities are left out altogether. Both connectors
+must be PostgreSQL connectors reading from the same database so the work can be done in a
+single statement.
+
+#### Type Parameters
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### joinConnector
+
+`IEntityStorageConnector`\<`U`\>
+
+The connector holding the entities to join to.
+
+##### joinOptions
+
+`IEntityStorageJoinOptions`\<`T`, `U`\>
+
+The properties to join on, the conditions, sort order, projection and
+paging for the primary entities, the optional grouping and group conditions, and the optional
+conditions, sort order and projection for the joined entities.
+
+#### Returns
+
+`Promise`\<\{ `entities`: `Partial`\<`T`\> & `object`[]; `cursor?`: `string`; \}\>
+
+All the entities for the storage matching the conditions with their joined entities,
+and a cursor which can be used to request more entities.
+
+#### Throws
+
+GeneralError if the join connector does not read from the same server and database.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.queryJoin`
+
+***
+
 ### count() {#count}
 
 > **count**(`conditions?`): `Promise`\<`number`\>

package/locales/en.json

@@ -7,8 +7,7 @@
 			"tableExists": "Table \"{tableName}\" created or it already exists",
 			"tableDropping": "Dropping table \"{tableName}\"",
 			"tableDropped": "Table \"{tableName}\" dropped",
-			"legacyIndexDropped": "Legacy index \"{indexName}\" dropped from table \"{tableName}\", \"{newIndexName}\" already covers the column",
-			"legacyIndexRenamed": "Legacy index \"{indexName}\" renamed to \"{newIndexName}\" on table \"{tableName}\""
+			"legacyIndexDropped": "Legacy index \"{indexName}\" dropped from table \"{tableName}\", \"{newIndexName}\" now covers the column"
 		}
 	},
 	"warn": {
@@ -26,6 +25,8 @@
 			"getFailed": "Unable to get entity \"{id}\"",
 			"removeFailed": "Unable to remove entity \"{id}\"",
 			"queryFailed": "The query failed",
+			"queryJoinFailed": "The join query failed",
+			"joinConnectorMismatch": "The join connector must be a PostgreSQL connector reading from the same server and database \"{database}\"",
 			"comparisonNotSupported": "Comparison operator \"{comparison}\" is not supported",
 			"conditionalNotSupported": "Conditional operator \"{operator}\" is not supported",
 			"entitySchemaPropertiesUndefined": "The entity schema properties are undefined",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity-storage-connector-postgresql",
-	"version": "0.10.1-next.1",
+	"version": "0.10.1-next.10",
 	"description": "PostgreSQL connector for relational persistence and advanced SQL features.",
 	"repository": {
 		"type": "git",
@@ -18,7 +18,7 @@
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.10.1-next.1",
+		"@twin.org/entity-storage-models": "0.10.1-next.10",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
 		"postgres": "3.4.9"