MySQL Mimic

Common errors

• TypeError: object MySQLServer.on_query() is not async

  cause Attempting to define `on_query` (or other server lifecycle methods like `on_connect`, `authenticate`) as a synchronous function after upgrading to `mysql-mimic` v3.0.0+.
  fix Ensure all custom server methods are defined using `async def`, e.g., `async def on_query(...)`.

• AttributeError: module 'mysql_mimic' has no attribute 'Authenticator'

  cause Using the old import path for `Authenticator` (or `SSLContextProvider`) after upgrading to `mysql-mimic` v3.0.0+.
  fix Update import statements to `from mysql_mimic.auth import Authenticator`.

• TypeError: 'str' object is not iterable

  cause The `on_query` method is returning a single string instead of a list of tuples as expected by `mysql-mimic` v3.0.0+.
  fix Ensure `on_query` always returns a `list` where each element is a `tuple` representing a row. E.g., `return [(f"Result: {query}",)]`.

• OSError: [Errno 98] Address already in use

  cause Another process (e.g., a real MySQL server or a previous run of mysql-mimic) is already listening on the configured port.
  fix Change the `port` argument in the `MyServer` constructor to an unused port (e.g., `3307`), or ensure no other applications are using the desired port.

Warnings

• breaking Version 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())`).
• breaking In 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`.
• gotcha The `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,)]`.
• gotcha Running `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.

Install

• pip install mysql-mimic Install stable version

Imports

• MySQLServer

  from mysql_mimic import MySQLServer

• Authenticator
  wrong:

  from mysql_mimic import Authenticator

  correct:

  from mysql_mimic.auth import Authenticator

  Moved to mysql_mimic.auth in v3.0.0
• SSLContextProvider
  wrong:

  from mysql_mimic import SSLContextProvider

  correct:

  from mysql_mimic.ssl import SSLContextProvider

  Moved to mysql_mimic.ssl in v3.0.0

Quickstart

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';"