Registry / database / mysql-mimic

mysql-mimic

JSON →
library3.0.4pypypi✓ verified 90d ago

mysql-mimic is a pure Python implementation of the MySQL server protocol. It enables developers to create fake MySQL servers to intercept connections, log queries, serve custom data, or test database clients without requiring a real MySQL instance. The current version, 3.0.2, primarily features an asynchronous API and aims for robust protocol emulation. Releases generally follow major breaking changes or significant feature additions, with major versions appearing every 2-3 years.

pip install mysql-mimic
INSTALL
IMPORT
SIG · MYSQL-MIMIC
M
mysql-mimic
databasepythonv3.0.4
Install
2.3s avg
Import
—
Disk
24MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v3.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 25.4MB
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 2.3s · import 0.000s · 26MB
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MysqlServer
✓ from mysql_mimic import MysqlServer
✗ from mysql_mimic import MySQLServer

This quickstart sets up a basic MySQL Mimic server that listens on port 3307 (or `MIMIC_PORT` env var). It uses a custom authenticator to allow any username with a pre-defined password (`MIMIC_TEST_PASSWORD` env var or 'super-secret-password'). The `on_query` method demonstrates how to respond to client queries with a list of tuples, mimicking a database result set. Remember to set the environment variable for the password before running.

import asyncio import logging import os from mysql_mimic import MySQLServer from mysql_mimic.auth import Authenticator logging.basicConfig(level=logging.INFO) # Define a test password via an environment variable for security best practices # In a real scenario, this would be a secure, complex password. MIMIC_PASSWORD = os.environ.get('MIMIC_TEST_PASSWORD', 'super-secret-password') MIMIC_HOST = os.environ.get('MIMIC_HOST', '127.0.0.1') MIMIC_PORT = int(os.environ.get('MIMIC_PORT', 3307)) # Use a non-standard port class MyAuthenticator(Authenticator): async def authenticate(self, username, password, database): logging.info(f"Auth attempt: user='{username}', db='{database}'") if password == MIMIC_PASSWORD: logging.info(f"Authentication successful for '{username}'") return True logging.warning(f"Authentication failed for '{username}' with provided password.") return False class MyServer(MySQLServer): async def on_query(self, query: str, database: str): logging.info(f"Query received on '{database}': '{query}'") # Return a list of tuples, mimicking a result set if query.lower().startswith("select version()"): return [("3.0.2",)] # Mimic current version of mysql-mimic elif query.lower().startswith("select 'hello world'"): return [("hello world from mysql-mimic!",)] else: return [(f"You queried: '{query}'",)] # This is the simplest way to run for a quickstart in an async context # Make sure to set MIMIC_TEST_PASSWORD in your environment before running, e.g.: # export MIMIC_TEST_PASSWORD="super-secret-password" # python your_script.py server = MyServer(authenticator=MyAuthenticator(), host=MIMIC_HOST, port=MIMIC_PORT) logging.info(f"Starting MySQL Mimic server on {MIMIC_HOST}:{MIMIC_PORT}") server.serve_forever_async() # To test from your terminal: # mysql -h 127.0.0.1 -P 3307 -u anyuser -p'super-secret-password' -e "SELECT 'Hello World';"
Debug
Known issues
breakingVersion 3.0.0 introduced a significant breaking change by moving to an entirely asynchronous API. All custom server methods like `on_query`, `on_connect`, `authenticate` (in `Authenticator`), and `serve()` itself are now `async def` and must be `await`ed or run within an `asyncio` event loop.
fix
Rewrite custom server and authenticator methods using `async def` and ensure the server is run in an `asyncio` event loop (e.g., `server.serve_forever_async()` or `asyncio.run(server.serve())`).
affects: >=3.0.0
breakingIn v3.0.0, `Authenticator` and `SSLContextProvider` classes were moved from the top-level `mysql_mimic` module to `mysql_mimic.auth` and `mysql_mimic.ssl` respectively.
fix
Update import statements: `from mysql_mimic.auth import Authenticator` and `from mysql_mimic.ssl import SSLContextProvider`.
affects: >=3.0.0
gotchaThe `on_query` method (since v3.0.0) must return a `list` of `tuple`s, representing rows and columns. Returning a single string, tuple, or non-list will lead to a `TypeError` at runtime.
fix
Ensure `on_query` always returns a `list` where each element is a `tuple` (e.g., `return [('column1', 'column2'), ('value1', 'value2')]`). For a single string result, use `return [(my_string_result,)]`.
affects: >=3.0.0
gotchaRunning `mysql-mimic` on the default MySQL port (3306) will fail if another MySQL server or process is already using that port. This is a common issue during development.
fix
It is highly recommended to use an alternative port like 3307 for `mysql-mimic` by passing `port=3307` to the `MySQLServer` constructor, or configuring via environment variables.
affects: All
Upgrade
Version history
3.0.4latest on PyPI · released May 5, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
14
Amazon
1
Resources
mysql-mimic — pip install mysql-mimic · libregistry