ENG-3666 Parallelize warm_async_pool connections with asyncio.gather

[erosselli]

Ticket ENG-3666

Description Of Changes

Parallelizes the warm_async_pool function to open all database connections concurrently using asyncio.gather instead of sequentially. This reduces pool warm-up time from N * RTT to ~1 RTT, which significantly improves startup time for deployments with large pool sizes and/or high-latency database connections.

Partial connection failures are handled gracefully via return_exceptions=True — successful connections are still tracked and cleaned up properly.

Code Changes

• src/fides/api/db/ctl_session.py: Replace sequential for loop with asyncio.gather for concurrent connection opening; also parallelize close() calls in the finally block
• tests/lib/test_ctl_session.py: New test file with unit tests (mocked engine) and an integration test (real async engine against Postgres)

Steps to Confirm

1. Run tests/lib/test_ctl_session.py — all 4 tests should pass
2. Verify pool warm-up logs show N/N connections on startup with a readonly pool configured

Pre-Merge Checklist

• Issue requirements met
• All CI pipelines succeeded
• CHANGELOG.md updated
  • Add a db-migration This indicates that a change includes a database migration label to the entry if your change includes a DB migration
  • Add a high-risk This issue suggests changes that have a high-probability of breaking existing code label to the entry if your change includes a high-risk change (i.e. potential for performance impact or unexpected regression) that should be flagged
  • Updates unreleased work already in Changelog, no new entry necessary
• UX feedback:
  • No UX review needed
• Followup issues:
  • No followup issues
• Database migrations:
  • No migrations
• Documentation:
  • No documentation updates required

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
fides-plus-nightly	Ignored	Preview	May 4, 2026 3:31pm
fides-privacy-center	Ignored		May 4, 2026 3:31pm

[erosselli]

/code-review

[claude]

Code Review — Parallelize async pool warm-up (#8097)

The change is well-motivated and the approach is sound: replacing the sequential connection loop with asyncio.gather(..., return_exceptions=True) correctly avoids paying N × RTT on startup. Partial-failure handling, improved logging, and the parallel close in finally are all nice additions. The test suite is thorough and covers the key cases.

One real issue

conn.close() gather in finally is missing return_exceptions=True — if any close call raises, the exception propagates out of the finally block, where it will either silence an in-flight exception or produce an unhandled error. The fix is one word: return_exceptions=True on line 192, consistent with how the open-gather is written.

Minor / nit

• The outer except Exception is now effectively dead code. With return_exceptions=True, individual coroutine failures are captured as return values and never raised, so there's no realistic path that reaches the catch. It could be removed or replaced with a clearer comment.
• import asyncio (new) and from asyncio import Lock (existing) coexist — minor inconsistency worth consolidating.
• import pytest in the test file is unused.

Overall this is a clean, focused improvement. The single actionable fix is the missing return_exceptions=True on the close-gather.

🔬 Codegraph: connected (48630 nodes)

💡 Write /code-review in a comment to re-run this review.

[claude]

src/fides/api/db/ctl_session.py:192

The asyncio.gather in the finally block is missing return_exceptions=True. If any conn.close() raises, the gather will propagate that exception, which in a finally block will silently replace any exception already in flight (or cause an unhandled error in the normal case). Since closing a connection is best-effort cleanup, this should mirror the approach used for opening:

await asyncio.gather(*(conn.close() for conn in connections), return_exceptions=True)

[erosselli]

I don't think closing a connection should fail ? if it does, a loud exception might be better

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.01%. Comparing base (5496449) to head (5e96c64).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8097      +/-   ##
==========================================
+ Coverage   84.98%   85.01%   +0.03%     
==========================================
  Files         633      633              
  Lines       41737    41736       -1     
  Branches     4886     4886              
==========================================
+ Hits        35471    35483      +12     
+ Misses       5157     5145      -12     
+ Partials     1109     1108       -1     

☔ 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.

[johnewart]

👍🏼