Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Overview

The async API provides:

  • Native asyncio integration: No thread pool wrapping required

  • Async connections: asyncConnect() function and AsyncConnection class

  • Async cursors: AsyncCursor class with async methods

  • Async connection pools: create_async_pool() for connection pooling

  • Context manager support: Async with statements for resource management

  • Same API surface: Familiar interface matching the synchronous API

Both the pure Python and C extension implementations support async operations.

Basic Async Connection

Single Connection

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.

Type the pool variable as mariadb.AsyncConnectionPool, not mariadb.ConnectionPool — the latter is the synchronous pool's type and won't match what create_async_pool() returns.

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

  1. Always use connection pools in production applications

  2. Use context managers for automatic resource cleanup

  3. Enable binary protocol for repeated parameterized queries

  4. Handle errors properly with try/except blocks

  5. Close pools during application shutdown

  6. Configure pool sizes based on your workload

  7. Use prepared statement caching for better performance

  8. 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?