fix(db2): avoid hanging queries on Node 26 - #18404

Pull Request Checklist

• Have you added new tests to prevent regressions?
• If a documentation update is necessary, have you opened a PR to the documentation repository? Not needed
• Did you update the typescript typings accordingly (if applicable)? Not applicable
• Does the description below contain a link to an existing issue (Closes #[issue]) or a description of the issue you are solving?
• Does the name of your PR follow our conventions?

Tests:

• packages/db2/src/connection-manager.test.ts (new test-unit script for the db2 package, plus a CI step) checks that open errors are still mapped to ConnectionRefusedError / ConnectionError.
• packages/core/test/integration/connection-manager.test.ts connects and disconnects with sinon fake timers installed, on every dialect. It fails on db2 if callIbmDb uses a patched setImmediate. The hang itself only happens with the real driver on Node >= 26.4, so the db2 integration jobs on Node 26 cover that part.

Description of Changes

On Node 26, the db2 oldest and db2 latest integration jobs time out in the root before all hook before any test runs. This already happened in the CI run for #18371 and now shows up on every PR (e.g. #17511).

Cause: ibm_db runs its callbacks straight from uv_queue_work completion handlers with Napi::Function::Call, not inside a Node.js callback scope. Until Node 26.3, promise continuations (and next ticks) queued from those callbacks still ran right away. Every check phase opened an InternalCallbackScope, and closing it drained them. nodejs/node#62969 (v26.4.0) skips that step when no native immediates are queued, so they now only run once another macrotask happens (a timer, for example). That PR is labelled backport-requested-v24.x, so Node 24 may be affected later too. The proper fix is for ibm_db to use Napi::AsyncWorker or a callback scope. As a result:

• await connection.prepare(sql) (ibm_db's promise API) never resumes, so sequelize.authenticate() hangs until Mocha's 30s timeout fires.
• The same applies to Sequelize's own promises that are resolved from ibm_db callbacks.

Minimal reproduction with plain ibm_db 4.0.1:

const db = new ibm.Database();
db.open(connStr, async () => {
  await db.prepare('SELECT 1 FROM SYSIBM.SYSDUMMY1');
  console.log('prepared'); // Node 24: right away. Node >= 26.4: only when some later macrotask runs
});

Fix: a small internal callIbmDb helper calls the callback form of an ibm_db method and settles the promise from setImmediate, which runs inside a proper callback scope so microtasks are drained. It is used for every async ibm_db call in the dialect: open, close, prepare, execute, and beginTransaction/commitTransaction/rollbackTransaction. It adds one event loop turn per driver call. The helper grabs setImmediate when the module loads, the same way test/integration/support.ts does for setTimeout. Without that, tests that install sinon fake timers (e.g. include/findAndCountAll) would stall every query.

Verified locally against DB2 12.1.5 (dev/db2/latest image) on Node 26.8.2: the full db2 integration suite passes (1769 passing, 16 pending). include/findAndCountAll also passes on Node 24.

List of Breaking Changes

None.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved reliability of DB2 connections, queries, and transactions.
  • DB2 communication failures with SQL30081N are reported as connection-refused errors, while authentication and other failures retain distinct error handling.
  • Original database errors remain available as causes for easier troubleshooting.
  • Improved compatibility with newer Node.js versions when completing DB2 operations.

• Tests

  • Added coverage for DB2 connection error classification and connection lifecycle behavior.
  • Added automated unit test execution for the DB2 package.