Auto-recreate connection on loop change

[abondar]

Fixed issue that forced you to implement hacks and use session scoped fixtures in tests

Now we automatically recreate pool on loop change, which is not a problem for tests. For prod we issue warning in such case, as it indicates that something has gone wrong

AI Summary:
This pull request introduces robust handling for event loop changes in database connections, especially relevant for async backends that bind connection pools to the event loop at creation time. Now, if a connection is accessed from a different event loop than it was created on, Tortoise will automatically recreate the connection and emit a warning. This behavior is documented, tested, and can be suppressed as needed (especially in test environments). The changes also add a dedicated warning class and update backend clients to track their bound event loop.

Event Loop Handling and Connection Safety:

• Added a _bound_loop attribute and _check_loop/_post_connect methods to BaseDBAsyncClient and all backend clients (e.g., asyncpg, aiomysql, sqlite, psycopg, odbc). These ensure each connection knows which event loop it was created on and can verify loop consistency. (tortoise/backends/base/client.py [1] [2]; tortoise/backends/asyncpg/client.py [3]; tortoise/backends/mysql/client.py [4]; tortoise/backends/odbc/client.py [5]; tortoise/backends/psycopg/client.py [6]; tortoise/backends/sqlite/client.py [7]

• Modified ConnectionHandler.get() to check for event loop changes using _check_loop(). If a change is detected, a new connection is transparently created, and a TortoiseLoopSwitchWarning is emitted. This prevents subtle bugs when test frameworks or application code switch event loops. (tortoise/connection.py [1] [2]

Testing and Warning Suppression:

• Added comprehensive tests for event loop validation and reconnection logic, ensuring that connections are properly recreated and warnings are emitted or suppressed as appropriate. (tests/test_connection.py [1] [2] [3] [4]; tests/test_query_api.py [5]

• Updated tortoise_test_context() to automatically suppress TortoiseLoopSwitchWarning in test environments, simplifying test setup. (tortoise/context.py tortoise/context.pyR576-R581)

Documentation and Developer Guidance:

• Expanded documentation to explain event loop binding, how Tortoise handles loop changes, the new warning, and best practices for both production and testing scenarios. Includes backend-specific notes and suppression instructions. (docs/connections.rst [1]; docs/contrib/unittest.rst [2]

Warnings and Developer Experience:

• Introduced TortoiseLoopSwitchWarning, a dedicated warning class with clear docstrings and usage guidance, to help developers identify and address event loop issues. (tortoise/warnings.py tortoise/warnings.pyR1-R18)

Overall, these changes make Tortoise ORM safer and more predictable in async environments, especially when dealing with test frameworks or mixed sync/async code.

[codspeed-hq]

Merging this PR will not alter performance

✅ 24 untouched benchmarks

---

_{Comparing tech/auto-reconnect-on-loop (e1b2b3e) with develop (48151d6)}

[coveralls]

Pull Request Test Coverage Report for Build 21914877818

Details

• 35 of 35 (100.0%) changed or added relevant lines in 9 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.04%) to 82.513%

---

Totals
Change from base Build 21899448865:	0.04%
Covered Lines:	10448
Relevant Lines:	12195

---

💛 - Coveralls