README.md

MySQL-Mimic

Pure-python implementation of the MySQL server wire protocol.

This can be used to create applications that act as a MySQL server.

Installation

pip install mysql-mimic

Usage

A minimal use case might look like this:

import asyncio

from mysql_mimic import MysqlServer, Session


class MySession(Session):
    async def query(self, expression, sql, attrs):
        print(f"Parsed abstract syntax tree: {expression}")
        print(f"Original SQL string: {sql}")
        print(f"Query attributes: {sql}")
        print(f"Currently authenticated user: {self.username}")
        print(f"Currently selected database: {self.database}")
        return [("a", 1), ("b", 2)], ["col1", "col2"]

    async def schema(self):
        # Optionally provide the database schema.
        # This is used to serve INFORMATION_SCHEMA and SHOW queries.
        return {
            "table": {
                "col1": "TEXT",
                "col2": "INT",
            }
        }

if __name__ == "__main__":
    server = MysqlServer(session_factory=MySession)
    asyncio.run(server.serve_forever())

Using sqlglot, the abstract Session class handles queries to metadata, variables, etc. that many MySQL clients expect.

To bypass this default behavior, you can implement the mysql_mimic.session.BaseSession interface.

See examples for more examples.

Authentication

MySQL-mimic has built in support for several standard MySQL authentication plugins:

• mysql_native_password
  • The client sends hashed passwords to the server, and the server stores hashed passwords. See the documentation for more details on how this works.
  • example
• mysql_clear_password
  • The client sends passwords to the server as clear text, without hashing or encryption.
  • This is typically used as the client plugin for a custom server plugin. As such, MySQL-mimic provides an abstract class, mysql_mimic.auth.AbstractClearPasswordAuthPlugin, which can be extended.
  • example
• mysql_no_login
  • The server prevents clients from directly authenticating as an account. See the documentation for relevant use cases.
• authentication_kerberos
  • Kerberos uses tickets together with symmetric-key cryptography, enabling authentication without sending passwords over the network. Kerberos authentication supports userless and passwordless scenarios.

By default, a session naively accepts whatever username the client provides.

Plugins are provided to the server by implementing mysql_mimic.IdentityProvider, which configures all available plugins and a callback for fetching users.

Custom plugins can be created by extending mysql_mimic.auth.AuthPlugin.

Development

You can install dependencies with make deps.

You can format your code with make format.

You can lint with make lint.

You can check type annotations with make types.

You can run tests with make test. This will build a coverage report in ./htmlcov/index.html.

You can run all the checks with make check.

You can build a pip package with make build.