Async/Await Support
Async/await support in MariaDB Connector/Python 2.0 enables non-blocking database operations via asyncConnect, AsyncCursor, and create_async_pool for asyncio-based Python applications.
MariaDB Connector/Python 2.0 introduces native async/await support for asynchronous database operations. This enables efficient database access in async applications like FastAPI, Starlette, and other asyncio-based frameworks.
API Reference
Connection API - Connection parameters, methods, and attributes
Cursor API - Cursor parameters, methods, and attributes
Connection Pooling API - Pool configuration and usage
Overview
The async API provides:
Native asyncio integration: No thread pool wrapping required
Async connections:
asyncConnect()function andAsyncConnectionclassAsync cursors:
AsyncCursorclass with async methodsAsync connection pools:
create_async_pool()for connection poolingContext manager support: Async
withstatements for resource managementSame API surface: Familiar interface matching the synchronous API
Both the pure Python and C extension implementations support async operations.
Basic Async Connection
Single Connection
Using Context Managers (Recommended)
Connection Parameters
Async connections support the same parameters as synchronous connections:
URI Connection
Keyword Arguments
Combining URI and Keywords
Async Cursor Operations
Executing Queries
Fetching Results
Inserting Data
Batch Operations
Async Transactions
Async Connection Pools
Connection pools are essential for web applications handling multiple concurrent requests.
Creating an Async Pool
Pool with URI
Pool Configuration
FastAPI Integration Example
Dependency Injection Pattern (Advanced)
The example above works well for a quick reference, but putting pool access directly in every route couples the database to the route and repeats the acquire/cursor boilerplate. For larger applications, move the pool lifecycle into its own module and expose a single dependency that routes request through FastAPI's Depends():
db.py — owns the pool and yields a request-scoped cursor:
main.py — routes depend on get_db instead of importing the pool directly:
Each request gets its own connection and cursor from get_db. FastAPI resumes the generator past yield once the response is sent, which runs the async with cleanup and returns the connection to the pool — so routes never call acquire()/cursor() themselves, and testing a route only requires overriding the get_db dependency.
Error Handling
Cursor Types
Dictionary Cursor
Returns rows as dictionaries instead of tuples:
Named Tuple Cursor
Returns rows as named tuples:
Unbuffered Cursor
Fetches rows on demand instead of buffering entire result set:
Binary Protocol with Async
Use binary protocol for better performance with prepared statements:
Performance Considerations
Connection Pooling
Always use connection pools in production:
Prepared Statement Caching
Enable for repeated queries (enabled by default):
Batch Operations
Use executemany() for bulk inserts:
Async vs Sync Performance
The async implementation provides:
No GIL contention: Pure Python async uses native asyncio I/O
Efficient concurrency: Handle thousands of concurrent connections
Lower latency: No thread pool overhead
Better resource usage: Event loop scheduling vs thread context switching
Note: Async excels in high-concurrency scenarios, not single-threaded throughput.
Complete Example
Best Practices
Always use connection pools in production applications
Use context managers for automatic resource cleanup
Enable binary protocol for repeated parameterized queries
Handle errors properly with try/except blocks
Close pools during application shutdown
Configure pool sizes based on your workload
Use prepared statement caching for better performance
Avoid creating connections per request - use pools instead
Migration from Sync to Async
Before (Synchronous)
After (Asynchronous)
With Context Managers
This page is: Copyright © 2026 MariaDB. All rights reserved.
Last updated
Was this helpful?

