feat(pool): add getStats() diagnostics method and fix execute() argument normalization

[IshitaSingh0822]

What this PR does

Two improvements to BasePool in lib/base/pool.js:

1. Fix pool.execute() argument normalization (|| → ??)

When calling execute(optionsObject, externalValues, cb), the original code used:

options.values = options.values || values;

This silently discards a valid options.values if it happens to be falsy.
Replaced with nullish coalescing so only a truly absent value falls back:

options.values = options.values ?? values;

Also changed the catch block in the no-callback path to emit on the pool
instead of throwing, keeping behavior consistent with pool.query().

---

2. Add pool.getStats() diagnostics method

Returns a lightweight snapshot of pool state — useful for health checks,
metrics exporters, and debugging pool exhaustion without reaching into
private internals:

const stats = pool.getStats();
// { all, free, queued, connectionLimit, queueLimit, closed }

console.log(`${stats.free}/${stats.all} free, ${stats.queued} queued`);

Files changed

File	Change
lib/base/pool.js	?? fix in execute(); new getStats(); emit instead of throw in no-cb catch
test/unit/test-pool-execute-polymorphic.test.cjs	11 unit tests — all call signatures, error paths, read-only errno, stats shape
typings/mysql/lib/pool.d.ts	PoolStats interface + getStats(): PoolStats declaration

Test results

PASS › 175 FAIL › 0
Full suite passed including integration tests against a live MySQL server via Docker.

Notes

• getStats() returns a plain object snapshot, not a live/reactive view
• queueLimit: 0 in stats means unlimited, matching pool config semantics
• No breaking changes — fully backwards compatible

[sidorares]

Hi @IshitaSingh0822 thanks for the contribution!

some notes:

• package.json / lockfile changes should not be part of this PR
• new tests use .mts extension
• new method need documentation change
• It might take a bit more time to review compared to patch version - once new API is there it's much harder to change

[IshitaSingh0822]

Hi @sidorares, thanks for the feedback! I've addressed all the points:

1. Removed package.json and package-lock.json changes from the PR
2. Renamed the test file to .mts extension
3. Added documentation for getStats() at website/docs/examples/connections/pool-get-stats.mdx

Happy to make any further changes if needed!

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.86%. Comparing base (52161e3) to head (50fb380).

Files with missing lines	Patch %	Lines
lib/base/pool.js	92.30%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4266      +/-   ##
==========================================
- Coverage   90.87%   90.86%   -0.02%     
==========================================
  Files          89       89              
  Lines       14501    14545      +44     
  Branches     1864     1872       +8     
==========================================
+ Hits        13178    13216      +38     
- Misses       1323     1329       +6     

Flag	Coverage Δ
compression-0	90.13% <92.30%> (-0.02%)	⬇️
compression-1	90.84% <92.30%> (-0.02%)	⬇️
static-parser-0	88.59% <92.30%> (-0.01%)	⬇️
static-parser-1	89.33% <92.30%> (-0.01%)	⬇️
tls-0	90.30% <92.30%> (-0.02%)	⬇️
tls-1	90.64% <92.30%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.