Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(infra): answer a rejected PostgreSQL import row with imported:false

Yudhi Armyndharisbf0a919b5ad0
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 7ad089cb5..1059c9d7b 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5724,7 +5724,7 @@ Replace all Data DB rows with the supplied export. **Destructive and transaction
}
```
-`warnings` are per-row import failures — they force a **rollback** and `imported:false`. `notices` are non-fatal operator messages (orphan-engine reconciliation detail) and never roll anything back. `restartRequired` is `true` from any of three causes: engines left pointing at sessions the restore removed (`force`), an orphan teardown that failed, or sessions running on another node, which this request has no channel to stop. `orphanedEngines` lists the session ids with a live engine the restored data no longer contains; `stoppedOrphanEngines`/`failedOrphanEngines` report how `stopOrphans` went.
+`warnings` are per-row import failures — they force a **rollback** and `imported:false`. On PostgreSQL the import stops at the first row the database rejects, so `warnings` holds the rows skipped before it and that one failure; SQLite lists every skipped and rejected row. `notices` are non-fatal operator messages (orphan-engine reconciliation detail) and never roll anything back. `restartRequired` is `true` from any of three causes: engines left pointing at sessions the restore removed (`force`), an orphan teardown that failed, or sessions running on another node, which this request has no channel to stop. `orphanedEngines` lists the session ids with a live engine the restored data no longer contains; `stoppedOrphanEngines`/`failedOrphanEngines` report how `stopOrphans` went.
**Orphan-engine pre-flight.** Before the transaction opens, any running engine whose session id is absent from `tables.sessions` is an orphan (the replace would delete its DB row, leaving an unstoppable engine writing into freshly restored tables). Default behaviour is to refuse with `409` listing those ids; `stopOrphans: true` stops them in-request and proceeds; `force: true` proceeds and leaves them running until restart.
diff --git a/src/database/postgres-utc.pg.spec.ts b/src/database/postgres-utc.pg.spec.ts
index 05e61f508..52d199d96 100644
--- a/src/database/postgres-utc.pg.spec.ts
+++ b/src/database/postgres-utc.pg.spec.ts
@@ -430,4 +430,24 @@ const SqliteSession = new EntitySchema<Record<string, unknown>>({
const carried = await repo.findOneByOrFail({ id: SESSION_ID });
expect(carried.leaseExpiresAt!.getTime()).toBeGreaterThanOrEqual(leaseExpiresAt.getTime());
});
+
+ it('rolls back a rejected row with its real error instead of an aborted-transaction failure', async () => {
+ await seedSession(SESSION_ID, new Date('2026-01-01T00:00:00.000Z'));
+ const archive = JSON.parse(JSON.stringify(await infra.exportData())) as { tables: MigrationTables };
+ const [row] = archive.tables.sessions;
+
+ const res = await infra.importData({
+ tables: {
+ sessions: [
+ { ...row, id: OLD_ID },
+ { ...row, id: OLD_ID, name: 'dup' },
+ ],
+ },
+ });
+
+ expect(res.imported).toBe(false);
+ expect(res.warnings).toHaveLength(1);
+ expect(res.warnings[0]).toContain('duplicate key');
+ expect((await ds.getRepository(Session).find()).map(s => s.id)).toEqual([SESSION_ID]);
+ });
});
diff --git a/src/modules/infra/infra-data.controller.spec.ts b/src/modules/infra/infra-data.controller.spec.ts
index 3cc12f5b5..752588c0d 100644
--- a/src/modules/infra/infra-data.controller.spec.ts
+++ b/src/modules/infra/infra-data.controller.spec.ts
@@ -458,6 +458,53 @@ describe('InfraDataController.importData round-trips export-data (no silent mess
expect(stored.nodeId).toBe('node-a');
});
+ it('answers imported:false with the real row error when PostgreSQL aborts the transaction', async () => {
+ await seedSession('s1');
+ await seedSession('s2');
+ const dump = await controller.exportData();
+
+ // PostgreSQL semantics on the SQLite harness: the first sessions INSERT fails, and from then on
+ // every statement except ROLLBACK fails with 25P02, as it would on an aborted PG transaction.
+ // The type flip is what the service keys its PostgreSQL handling on.
+ const realOptions = ds.options;
+ Object.defineProperty(ds, 'options', { value: { ...realOptions, type: 'postgres' }, configurable: true });
+ // better-sqlite3 hands out one runner per DataSource, so the patch is undone on that instance.
+ const runner = ds.createQueryRunner();
+ const realQuery = runner.query.bind(runner);
+ jest.spyOn(ds, 'createQueryRunner').mockImplementation(() => {
+ let aborted = false;
+ runner.query = ((...callArgs: Parameters<typeof realQuery>) => {
+ const sql = callArgs[0];
+ if (aborted && sql !== 'ROLLBACK') {
+ return Promise.reject(
+ new Error('current transaction is aborted, commands ignored until end of transaction block'),
+ );
+ }
+ if (/INSERT INTO sessions/.test(sql)) {
+ aborted = true;
+ return Promise.reject(new Error('duplicate key value violates unique constraint "PK_sessions"'));
+ }
+ return realQuery(...callArgs);
+ }) as typeof runner.query;
+ return runner;
+ });
+
+ let res: Awaited<ReturnType<typeof controller.importData>>;
+ try {
+ res = await controller.importData({ tables: dump.tables });
+ } finally {
+ jest.restoreAllMocks();
+ runner.query = realQuery;
+ Object.defineProperty(ds, 'options', { value: realOptions, configurable: true });
+ }
+
+ expect(res.imported).toBe(false);
+ expect(res.warnings).toEqual([
+ 'Failed to import session s1: duplicate key value violates unique constraint "PK_sessions"',
+ ]);
+ expect((await ds.getRepository(Session).find()).map(s => s.id).sort()).toEqual(['s1', 's2']);
+ });
+
it('leaves a session that had no claim unclaimed rather than inventing one', async () => {
await seedSession('s1');
diff --git a/src/modules/infra/infra-data.service.ts b/src/modules/infra/infra-data.service.ts
index 0b8a088c2..deae76223 100644
--- a/src/modules/infra/infra-data.service.ts
+++ b/src/modules/infra/infra-data.service.ts
@@ -675,7 +675,7 @@ export class InfraDataService {
// SQLite only: archived datetime values are normalized to the form TypeORM writes there, so a
// PostgreSQL-made backup compares and sorts like rows the app wrote itself.
const datetimeColumns = isPostgres ? undefined : sqliteDatetimeColumns(this.dataDataSource);
- for (const importer of TABLE_IMPORTERS) {
+ restore: for (const importer of TABLE_IMPORTERS) {
const rows = data.tables[importer.key];
if (!rows?.length) continue;
const dateColumns = datetimeColumns?.get(importer.key) ?? [];
@@ -706,6 +706,9 @@ export class InfraDataService {
warnings.push(
`Failed to import ${importer.label} ${importer.id(row)}: ${err instanceof Error ? err.message : String(err)}`,
);
+ // PostgreSQL aborts the transaction on a failed statement: every later one would fail with
+ // "current transaction is aborted" and bury this row's real error. Stop at the first.
+ if (isPostgres) break restore;
}
}
}
@@ -716,12 +719,33 @@ export class InfraDataService {
// bug it fixes — on PostgreSQL a failed statement aborts the transaction, so the COMMIT would
// execute as a ROLLBACK and the endpoint would report a fully discarded import as a success,
// with per-table counts, to an operator restoring after data loss.
- try {
- await restoreSessionOwnership(preservedOwnership, insert, ownershipReadAt);
- } catch (error) {
- warnings.push(
- `Failed to restore session ownership: ${error instanceof Error ? error.message : String(error)}`,
- );
+ // Skipped once a row has failed: the rollback below is already certain, and on PostgreSQL the
+ // aborted transaction would only add a misleading warning.
+ if (warnings.length === 0) {
+ try {
+ await restoreSessionOwnership(preservedOwnership, insert, ownershipReadAt);
+ } catch (error) {
+ warnings.push(
+ `Failed to restore session ownership: ${error instanceof Error ? error.message : String(error)}`,
+ );
+ }
+ }
+
+ // "Replace all data" must be all-or-nothing: the import already DELETEd every row, so if any
+ // INSERT failed we must roll back (restoring the pre-import data) rather than commit a
+ // half-wiped DB and report success. A partial restore reported as imported:true was how
+ // message history could silently vanish on a SQLite->Postgres migration. It must precede
+ // every further statement: on PostgreSQL a failure has aborted the transaction, so the
+ // normalization UPDATE below would throw and turn this answer into a 500.
+ if (warnings.length > 0) {
+ await queryRunner.rollbackTransaction();
+ return {
+ imported: false,
+ counts,
+ warnings,
+ notices,
+ ...engineStateAfterRollback,
+ };
}
// Normalize imported statuses the same way boot does: an ACTIVE status (ready,
@@ -756,21 +780,6 @@ export class InfraDataService {
);
}
- // "Replace all data" must be all-or-nothing: the import already DELETEd every row, so if any
- // INSERT failed we must roll back (restoring the pre-import data) rather than commit a
- // half-wiped DB and report success. A partial restore reported as imported:true was how
- // message history could silently vanish on a SQLite->Postgres migration.
- if (warnings.length > 0) {
- await queryRunner.rollbackTransaction();
- return {
- imported: false,
- counts,
- warnings,
- notices,
- ...engineStateAfterRollback,
- };
- }
-
// A wrong/empty/garbage backup file restores zero rows but the DELETE already ran — committing
// would silently WIPE the database and report success. Refuse it and roll back instead. (#488 review)
const totalRestored = Object.values(counts).reduce((sum, n) => sum + n, 0);