{"id":15658950,"url":"https://github.com/long2ice/asyncmy","last_synced_at":"2025-04-12T22:22:52.895Z","repository":{"id":45198702,"uuid":"336724491","full_name":"long2ice/asyncmy","owner":"long2ice","description":"A fast asyncio MySQL/MariaDB driver with replication protocol support","archived":false,"fork":false,"pushed_at":"2024-04-24T16:10:37.000Z","size":617,"stargazers_count":205,"open_issues_count":27,"forks_count":21,"subscribers_count":6,"default_branch":"dev","last_synced_at":"2024-04-24T18:21:40.778Z","etag":null,"topics":["asyncio","binlog","connector","cython","mysql","replication"],"latest_commit_sha":null,"homepage":"https://github.com/long2ice/asyncmy","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/long2ice.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://sponsor.long2ice.io"]}},"created_at":"2021-02-07T07:06:51.000Z","updated_at":"2024-06-18T15:33:43.489Z","dependencies_parsed_at":"2024-06-18T15:43:35.099Z","dependency_job_id":null,"html_url":"https://github.com/long2ice/asyncmy","commit_stats":{"total_commits":138,"total_committers":6,"mean_commits":23.0,"dds":0.04347826086956519,"last_synced_commit":"2d18f0df1ca1946f1dbfaa0d31870ccd7bc82e4d"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fasyncmy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fasyncmy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fasyncmy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fasyncmy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/long2ice","download_url":"https://codeload.github.com/long2ice/asyncmy/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248638602,"owners_count":21137688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","binlog","connector","cython","mysql","replication"],"created_at":"2024-10-03T13:14:29.563Z","updated_at":"2025-04-12T22:22:52.858Z","avatar_url":"https://github.com/long2ice.png","language":"Python","funding_links":["https://sponsor.long2ice.io"],"categories":["Python"],"sub_categories":[],"readme":"# asyncmy - A fast asyncio MySQL/MariaDB driver\n\n[![image](https://img.shields.io/pypi/v/asyncmy.svg?style=flat)](https://pypi.python.org/pypi/asyncmy)\n[![image](https://img.shields.io/github/license/long2ice/asyncmy)](https://github.com/long2ice/asyncmy)\n[![pypi](https://github.com/long2ice/asyncmy/actions/workflows/pypi.yml/badge.svg)](https://github.com/long2ice/asyncmy/actions/workflows/pypi.yml)\n[![ci](https://github.com/long2ice/asyncmy/actions/workflows/ci.yml/badge.svg)](https://github.com/long2ice/asyncmy/actions/workflows/ci.yml)\n\n## Introduction\n\n`asyncmy` is a fast asyncio MySQL/MariaDB driver, which reuse most of [pymysql](https://github.com/PyMySQL/PyMySQL)\nand [aiomysql](https://github.com/aio-libs/aiomysql) but rewrite core protocol with [cython](https://cython.org/) to\nspeedup.\n\n## Features\n\n- API compatible with [aiomysql](https://github.com/aio-libs/aiomysql).\n- Faster by [cython](https://cython.org/).\n- MySQL replication protocol support with `asyncio`.\n- Tested both MySQL and MariaDB in [CI](https://github.com/long2ice/asyncmy/blob/dev/.github/workflows/ci.yml).\n\n## Benchmark\n\nThe result comes from [benchmark](./benchmark).\n\n\u003e The device is iMac Pro(2017) i9 3.6GHz 48G and MySQL version is 8.0.26.\n\n![benchmark](./images/benchmark.png)\n\n### Conclusion\n\n- There is no doubt that `mysqlclient` is the fastest MySQL driver.\n- All kinds of drivers have a small gap except `select`.\n- `asyncio` could enhance `insert`.\n- `asyncmy` performs remarkable when compared to other drivers.\n\n## Install\n\n```shell\npip install asyncmy\n```\n\n### Installing on Windows\n\nTo install asyncmy on Windows, you need to install the tools needed to build it.\n\n1. Download *Microsoft C++ Build Tools* from https://visualstudio.microsoft.com/visual-cpp-build-tools/\n2. Run CMD as Admin (not required but recommended) and navigate to the folder when your installer is downloaded\n3. Installer executable should look like this `vs_buildtools__XXXXXXXXX.XXXXXXXXXX.exe`, it will be easier if you rename\n   it to just `vs_buildtools.exe`\n4. Run this command (Make sure you have about 5-6GB of free storage)\n\n```shell\nvs_buildtools.exe --norestart --passive --downloadThenInstall --includeRecommended --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Workload.MSBuildTools\n```\n\n5. Wait until the installation is finished\n6. After installation will finish, restart your computer\n7. Install asyncmy via PIP\n\n```shell\npip install asyncmy\n```\n\nNow you can uninstall previously installed tools.\n\n## Usage\n\n### Use `connect`\n\n`asyncmy` provides a way to connect to MySQL database with simple factory function `asyncmy.connect()`. Use this\nfunction if you want just one connection to the database, consider connection pool for multiple connections.\n\n```py\nimport asyncio\nimport os\n\nfrom asyncmy import connect\nfrom asyncmy.cursors import DictCursor\n\n\nasync def run():\n    conn = await connect(user=os.getenv(\"DB_USER\"), password=os.getenv(\"DB_PASSWORD\", \"\"))\n    async with conn.cursor(cursor=DictCursor) as cursor:\n        await cursor.execute(\"CREATE DATABASE IF NOT EXISTS test\")\n        await cursor.execute(\"\"\"\n            \"\"\"\nCREATE TABLE IF NOT EXISTS test.`asyncmy` (\n    `id`       int primary key AUTO_INCREMENT,\n    `decimal`  decimal(10, 2),\n    `date`     date,\n    `datetime` datetime,\n    `float`    float,\n    `string`   varchar(200),\n    `tinyint`  tinyint\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci\n            \"\"\".strip()\n        )\n    await conn.ensure_closed()\n\n\nif __name__ == \"__main__\":\n    asyncio.run(run())\n```\n\n### Use `pool`\n\n`asyncmy` provides connection pool as well as plain Connection objects.\n\n```py\nimport asyncmy\nimport asyncio\n\n\nasync def run():\n    pool = await asyncmy.create_pool()\n    async with pool.acquire() as conn:\n        async with conn.cursor() as cursor:\n            await cursor.execute(\"SELECT 1\")\n            ret = await cursor.fetchone()\n            assert ret == (1,)\n    pool.close()\n    await pool.wait_closed()\n\nif __name__ == '__main__':\n    asyncio.run(run())\n```\n\n## Replication\n\n`asyncmy` supports MySQL replication protocol\nlike [python-mysql-replication](https://github.com/noplay/python-mysql-replication), but powered by `asyncio`.\n\n```py\nfrom asyncmy import connect\nfrom asyncmy.replication import BinLogStream\nimport asyncio\n\n\nasync def run():\n    conn = await connect()\n    ctl_conn = await connect()\n\n    stream = BinLogStream(\n        conn,\n        ctl_conn,\n        1,\n        master_log_file=\"binlog.000172\",\n        master_log_position=2235312,\n        resume_stream=True,\n        blocking=True,\n    )\n    async for event in stream:\n        print(event)\n    await conn.ensure_closed()\n    await ctl_conn.ensure_closed()\n\n\nif __name__ == '__main__':\n    asyncio.run(run())\n```\n\n## ThanksTo\n\n\u003e asyncmy is build on top of these awesome projects.\n\n- [pymysql](https://github/pymysql/PyMySQL), a pure python MySQL client.\n- [aiomysql](https://github.com/aio-libs/aiomysql), a library for accessing a MySQL database from the asyncio.\n- [python-mysql-replication](https://github.com/noplay/python-mysql-replication), pure Python Implementation of MySQL\n  replication protocol build on top of PyMYSQL.\n\n## License\n\nThis project is licensed under the [Apache-2.0](./LICENSE) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flong2ice%2Fasyncmy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flong2ice%2Fasyncmy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flong2ice%2Fasyncmy/lists"}