# mariadb-corporation/mariadb-connector-python architecture

> Architecture diagram of the GitHub repository mariadb-corporation/mariadb-connector-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mariadb-corporation/mariadb-connector-python
- Repository: https://github.com/mariadb-corporation/mariadb-connector-python

## Overview

##### Project Type and Purpose
- This is a database-connector library (client-side driver) that implements the Python DB API 2.0 (PEP-249).
- Users import it in their Python applications to communicate with MariaDB/MySQL servers.
- It combines pure-Python modules, C extensions, and links to the MariaDB Connector/C client library.

##### File Structure
- Top-level modules and packages:
- mariadb/           ← Pure-Python API modules (connection, cursors, constants, pooling)
- mariadb_*.c files  ← C-extension sources (binding layer, codecs, parser, exceptions)
- /           ← C headers for building the extension
- helper/            ← Code-gen scripts for error constants
- Build and configuration:
- setup.py, pyproject.toml, site.cfg
- .github/, .travis.yml CI workflows
- Documentation and examples:
- docs/source/      ← Sphinx reST files (API reference, usage, connection, pooling)
- docs/examples/    ← Python scripts demonstrating basic usage
- Testing:
- testing/bench.py and testing/benchmarks/ for performance tests
- testing/test/      ← Unit and integration tests under pytest or unittest

##### Extract Insights from README
- Confirms it’s a DB API 2.0-compliant client implemented in C.
- Depends on the MariaDB Connector/C library for network I/O.
- Targets Python 3.7+ and LGPL-2.1 licensing.

##### Main Components
a. Public-API Layer (Python)
- mariadb.dbapi20, connections.py, cursors.py, connectionpool.py
- Constants packages under mariadb/constants
- Exception handling modules
b. C-Extension Layer
- mariadb.c (module init and Python–C dispatch)
- mariadb_connection.c, mariadb_cursor.c, mariadb_exception.c, mariadb_parser.c
- mariadb_codecs.c (character-set conversions)
c. Native Client Library
- MariaDB Connector/C (external C library)
- libmariadb.so / msvcr dependencies
d. Network (External Service)
- MariaDB/MySQL server over TCP/IP or socket
e. Support Infrastructure (secondary, shown periphery)
- Build system (setup.py, C compiler)
- CI pipelines (.github/workflows, .travis.yml)
- Documentation site generator (Sphinx)
- Test harness and benchmarking suite

##### Architectural Patterns & Principles
- Layered architecture: clear separation between API, native binding, and network client.
- Adapter pattern: C extension adapts the C client library to Python’s DB-API interface.
- Factory pattern: connectionpool creates and manages Connection objects.
- Single Responsibility: separate modules for constants, errors, parsing, and codecs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Public-API Layer"
        direction TB
        dbapi["dbapi20.py"]:::python
        conn["connections.py"]:::python
        pool["connectionpool.py"]:::python
        curs["cursors.py"]:::python
        const["constants/"]:::python
        field["field.py"]:::python
    end

    subgraph "C-Extension Layer"
        direction TB
        mmod["mariadb.c"]:::cext
        cconn["mariadb_connection.c"]:::cext
        ccurs["mariadb_cursor.c"]:::cext
        excite["mariadb_exception.c"]:::cext
        parse["mariadb_parser.c"]:::cext
        codec["mariadb_codecs.c"]:::cext
    end

    subgraph "Native Client Library"
        direction TB
        headers["mariadb_python.h"]:::native
        docheaders["docs/"]:::native
        lib["MariaDB Connector/C"]:::native
    end

    dbServer["MariaDB/MySQL Server"]:::external

    subgraph "Support Infrastructure"
        direction TB
        build["setup.py<br/>pyproject.toml<br/>site.cfg"]:::support
        helper["helper/create_errconst.py"]:::support
        ci[".github/workflows/ci.yml<br/>.github/workflows/release.yml<br/>.travis.yml"]:::support
        docs["docs/source/"]:::support
        examples["docs/examples/basic01.py"]:::support
        test["testing/test/"]:::support
        bench["testing/bench.py<br/>testing/bench_init.py"]:::support
        benchb["testing/benchmarks/"]:::support
    end

    %% Application entry
    app["Application Code"]:::external

    %% Data Flows
    app -->|"import & call"| dbapi
    dbapi -->|"init C binding"| mmod
    conn --> mmod
    curs --> mmod
    pool --> mmod
    mmod -->|"C API calls"| lib
    cconn --> lib
    ccurs --> lib
    excite --> lib
    parse --> lib
    codec --> lib
    lib -->|"TCP/IP"| dbServer
    dbServer -->|"result bytes"| lib
    lib --> parse
    parse --> dbapi
    mmod --> excite
    excite --> dbapi
    pool --> conn

    %% Click Events
    click dbapi "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/dbapi20.py"
    click conn "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/connections.py"
    click pool "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/connectionpool.py"
    click curs "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/cursors.py"
    click const "https://github.com/mariadb-corporation/mariadb-connector-python/tree/1.1/mariadb/constants/"
    click field "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/field.py"
    click mmod "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/mariadb.c"
    click cconn "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/mariadb_connection.c"
    click ccurs "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/mariadb_cursor.c"
    click excite "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/mariadb_exception.c"
    click parse "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/mariadb_parser.c"
    click codec "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/mariadb/mariadb_codecs.c"
    click headers "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/include/mariadb_python.h"
    click docheaders "https://github.com/mariadb-corporation/mariadb-connector-python/tree/1.1/include/docs/"
    click build "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/setup.py"
    click helper "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/helper/create_errconst.py"
    click ci "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/.github/workflows/ci.yml"
    click docs "https://github.com/mariadb-corporation/mariadb-connector-python/tree/1.1/docs/source/"
    click examples "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/docs/examples/basic01.py"
    click test "https://github.com/mariadb-corporation/mariadb-connector-python/tree/1.1/testing/test/"
    click bench "https://github.com/mariadb-corporation/mariadb-connector-python/blob/1.1/testing/bench.py"
    click benchb "https://github.com/mariadb-corporation/mariadb-connector-python/tree/1.1/testing/benchmarks/"

    %% Styles
    classDef python fill:#D0E6FF,stroke:#0366d6,stroke-width:1px;
    classDef cext fill:#DFFFE0,stroke:#22863a,stroke-width:1px;
    classDef native fill:#FFE4B5,stroke:#D2691E,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px;
    classDef support fill:#E8E8E8,stroke:#999999,stroke-width:1px;
```
