aio-libs / aiomysql

aiomysql is a library for accessing a MySQL database from the asyncio
https://aiomysql.rtfd.io
MIT License
1.74k stars 255 forks source link

Better documentation on how connection/cursor work #871

Open ZisIsNotZis opened 1 year ago

ZisIsNotZis commented 1 year ago

Is your feature request related to a problem?

I'm using aiohttp.web and aiomysql. Before reading the source code, I had no idea weather I should:

Since the traditional "blocking" model uses the third method, and the simple examples given does not use connection pool, I thought method 1 or 2 are also fine.

But after I read the source code, I found that connection is essentially a state machine, and cursor is a “fake” proxy to it. Reusing the same connection at the same time might cause problems. (Correct me if I'm wrong)

Describe the solution you'd like

A better documentation is deserved, especially in README.md, that highlights the importance of using connection pool in concurrent use case.

Describe alternatives you've considered

I'm not sure weather mysql supports pipelining in the same connection (like http pipelining). If it does, maybe cursors can be implemented that way to support concurrent connection reuse?

Additional context

No response

Code of Conduct