Skip to content

v2.0.0

Breaking Changes

v2.0.0 is a completely refactored version that is incompatible with v1. Main changes include:

1. Architecture Refactoring

  • Separated Engine and AsMysql Classes
  • New Engine class: Independent MySQL connection engine, can be used standalone
  • AsMysql class: Business logic development base class, accesses Engine through client attribute
  • This design completely separates connection management and business logic

2. Result Class Changes

  • Error Attribute Renaming
  • Result.err → Result.error
  • More compliant with Python naming conventions

3. API Changes

  • Connection Method Changes
  • v1: Auto-connect after inheriting AsMysql

  • v2: Need to explicitly create Engine and call connect()

  • Execution Method Changes

  • v1: AsMysql self.client.execute(...)
  • v2: AsMysql self.client.execute(...) (unchanged, but client is now an Engine instance)

New Features

1. Engine Class

A brand new connection engine class providing the following features:

  • URL Connection String Support 

    engine = Engine(url="mysql://user:password@host:port/?charset=utf8mb4")

  • Connection Status Monitoring 

    status = engine.status
# Returns detailed connection pool status information

  • Flexible Connection Management

  • Support for async with context manager
  • Support for await engine() syntax

  • Support for await engine syntax

  • Connection Pool Configuration

  • min_pool_size: Minimum connections
  • max_pool_size: Maximum connections
  • pool_recycle: Idle connection recycle time
  • connect_timeout: Connection timeout

2. Result Class Enhancements

  • Error Information Access
  • error_no: Get MySQL error code
  • error_msg: Get MySQL error message

  • error: Get complete error exception object

  • Streaming Query Support 

    result = await engine.execute("SELECT * FROM large_table", stream=True)
async for row in result:
    process(row)  # Process row by row without memory consumption

  • Context Manager Support 

    async with engine.execute("SELECT * FROM users") as result:
    data = await result.fetch_all()

  • Async Iterator Support 

    # Method 1: Direct iteration
async for row in engine.execute("SELECT * FROM users"):
    print(row)

# Method 2: Iterate Result
result = await engine.execute("SELECT * FROM users")
async for row in result:
    print(row)

  • Custom Result Types 

    # Supports tuple (default), dict, or custom model classes
result = await engine.execute(
    "SELECT * FROM users",
    result_class=dict  # or custom Pydantic model
)

3. Execution Method Enhancements

  • execute() Method
  • Support for stream parameter: Enable streaming query
  • Support for result_class parameter: Specify return result type
  • Support for commit parameter: Control transaction commit

  • Support for multiple calling methods:

    • result = await engine.execute(...)
    • async with engine.execute(...) as result:
    • async for item in engine.execute(...):

  • execute_many() Method

  • Batch execute SQL statements
  • Support for same parameter options

4. Type Hints

  • Complete type hint support
  • Support for generic types (Result[T])
  • IDE-friendly code completion

5. Testing

  • New pytest test suite
  • Covers main functional scenarios
  • Support for Mock testing

Updates

1. Package Management Tool

  • Use uv as package management tool
  • Faster dependency installation speed
  • Better dependency resolution

2. Code Quality

  • Improved code structure
  • Better error handling
  • Clearer docstrings

Core Features

v2 version retains the core features of v1:

  1. Easy to Use
  2. asmysql is an easy-to-use library that wraps aiomysql

  3. Provides more friendly API

  4. Connection Pool Management

  5. Automatic MySQL connection pool management
  6. Support for reconnection mechanism

  7. Connection pool status monitoring

  8. Error Handling

  9. Global automatic capture of MysqlError errors
  10. Provides error code and error message access

  11. Elegant error handling mechanism

  12. Separation of Execution and Retrieval

  13. Separation of SQL statement execution and result retrieval
  14. Support for multiple data retrieval methods

  15. Flexible result processing

  16. Type Hints

  17. Complete Python type hints
  18. IDE-friendly code completion

  19. Type safety

  20. Business Logic Development

  21. Directly inherit AsMysql class for logic development
  22. Clear code organization
  23. Easy to test and maintain