# dingmaotu/mql-sqlite3 architecture

> Architecture diagram of the GitHub repository dingmaotu/mql-sqlite3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dingmaotu/mql-sqlite3
- Repository: https://github.com/dingmaotu/mql-sqlite3

## Overview

##### Project Type and Purpose
- This is an **open-source binding library** that exposes the native SQLite3 C API to the MQL language (MetaTrader 4/5).
- Its goal is to let MQL scripts call SQLite operations (open, query, backup, etc.) via a small header-only wrapper and a precompiled Windows DLL.

##### File-Structure Analysis
- **Include/SQLite3/**: MQL header files (.mqh) implementing classes and functions mirroring SQLite3’s C API (SQLite3, Statement, Blob, Backup, Vfs, plus common/defines/imports).
- **Library/MT4** & **Library/MT5**: Precompiled 32-bit and 64-bit SQLite3 DLLs.
- **Scripts/Test/**: Example MQL4 script(s) (.mq4/.mq5) that demonstrate initialization, table creation, querying, and cleanup.

##### Core Components
a. **MetaTrader Runtime**
- Hosts MQL scripts, loads DLLs from terminal’s Library folder, compiles and executes .mqh-backed code.
b. **MQL Script**
- `TestSQLite3.mq4/.mq5` call methods like `SQLite3::initialize()`, `Statement::step()`, `SQLite3::shutdown()`.
c. **Wrapper Layer (Include/SQLite3 .mqh files)**
- Provides MQL classes matching C API:
- SQLite3.mqh (connection)
- Statement.mqh (SQL statements)
- Blob.mqh, Backup.mqh, Vfs.mqh, etc.
- `Imports.mqh` defines DLL-imported functions.
d. **SQLite3 DLL**
- Precompiled native library implementing the actual SQLite3 engine. Two flavors: MT4 (32-bit) and MT5 (64-bit).
e. **Database File**
- A .db file stored under `MQL4\Files` or `MQL5\Files` (persistent storage on disk).

##### Component Relationships and Data Flow
- **MQL Script → Wrapper Layer**
Includes `.mqh` files; calls class methods (e.g., `db.step()`).
- **Wrapper Layer → SQLite3 DLL**
Via Windows DLL imports; marshals MQL data to UTF-8 and calls into native code.
- **SQLite3 DLL → Storage**
Reads/writes the `.db` file on disk, manages pages, indexes, transactions.
- **DLL → Wrapper Layer**
Returns status codes, result rows, blobs, errors.
- **Wrapper Layer → MQL Script**
Converts results back to MQL types, exposes them to the script.

##### Architectural Patterns and Principles
- **Foreign Function Interface (FFI)**: MQL ↔ DLL boundary.
- **Wrapper/Facade**: Header classes abstract low-level C calls into idiomatic MQL methods.
- **Version Compatibility**: Single headers support both MT4 and MT5; separate DLLs for word-size.
- **UTF-8 Unification**: All strings converted to/from UTF-8 at the boundary.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "MetaTrader Terminal"
        direction TB
        Script["TestSQLite3.mq4"]:::mql
        subgraph "Wrapper Layer (.mqh files)"
            direction TB
            SQLite3Core["SQLite3.mqh"]:::wrapper
            Statement["Statement.mqh"]:::wrapper
            Blob["Blob.mqh"]:::wrapper
            Backup["Backup.mqh"]:::wrapper
            Vfs["Vfs.mqh"]:::wrapper
            Common["Common.mqh"]:::wrapper
            Defines["Defines.mqh"]:::wrapper
            Imports["Imports.mqh"]:::wrapper
        end
        subgraph "SQLite3 DLLs"
            direction TB
            MT4["Library/MT4 (SQLite3 MT4 DLL)"]:::dll
            MT5["Library/MT5 (SQLite3 MT5 DLL)"]:::dll
        end
    end

    DBFile["SQLite Database File (.db)"]:::storage

    Script -->|"#include `<Statement.mqh>`\ncalls initialize(), step()"| Statement
    Statement -->|"bind()/step() → C API"| Imports
    Imports -->|"dllimport sqlite3_open_v2(), etc."| MT4
    Imports -->|"dllimport sqlite3_open_v2(), etc."| MT5
    MT4 -->|"reads/writes pages, executes SQL"| DBFile
    MT5 -->|"reads/writes pages, executes SQL"| DBFile
    DBFile -->|"returns rows, status codes (UTF-8)"| MT4
    DBFile -->|"returns rows, status codes (UTF-8)"| MT5
    MT4 -->|"status codes, row blobs"| Imports
    MT5 -->|"status codes, row blobs"| Imports
    Imports -->|"convert to MQL types"| Statement
    Statement -->|"result objects"| Script

    click Script "https://github.com/dingmaotu/mql-sqlite3/blob/master/Scripts/Test/TestSQLite3.mq4"
    click SQLite3Core "https://github.com/dingmaotu/mql-sqlite3/blob/master/Include/SQLite3/SQLite3.mqh"
    click Statement "https://github.com/dingmaotu/mql-sqlite3/blob/master/Include/SQLite3/Statement.mqh"
    click Blob "https://github.com/dingmaotu/mql-sqlite3/blob/master/Include/SQLite3/Blob.mqh"
    click Backup "https://github.com/dingmaotu/mql-sqlite3/blob/master/Include/SQLite3/Backup.mqh"
    click Vfs "https://github.com/dingmaotu/mql-sqlite3/blob/master/Include/SQLite3/Vfs.mqh"
    click Common "https://github.com/dingmaotu/mql-sqlite3/blob/master/Include/SQLite3/Common.mqh"
    click Defines "https://github.com/dingmaotu/mql-sqlite3/blob/master/Include/SQLite3/Defines.mqh"
    click Imports "https://github.com/dingmaotu/mql-sqlite3/blob/master/Include/SQLite3/Imports.mqh"
    click MT4 "https://github.com/dingmaotu/mql-sqlite3/tree/master/Library/MT4"
    click MT5 "https://github.com/dingmaotu/mql-sqlite3/tree/master/Library/MT5"

    classDef mql fill:#cce5ff,stroke:#004085,color:#004085
    classDef wrapper fill:#d4edda,stroke:#155724,color:#155724
    classDef dll fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
