# diesel-rs/diesel architecture

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

- Interactive diagram: https://gitdiagram.com/diesel-rs/diesel
- Repository: https://github.com/diesel-rs/diesel

## Overview

##### Project Type and Purpose
- This is an open-source Rust workspace providing a type-safe ORM and query builder (the “diesel” crate), accompanying derive macros, CLI tooling, migration support, benchmarking, and examples for Postgres, MySQL, and SQLite backends.

##### High-Level File Structure Analysis
- Top-level crates/directories:
- diesel (core ORM + query builder)
- diesel_derives (custom derive macros)
- diesel_dynamic_schema (runtime-driven schema queries)
- diesel_migrations (migration DSL and embed macros)
- diesel_cli (command-line tool wrapping core + migrations)
- diesel_bench (benchmarks harness)
- diesel_tests & diesel_compile_tests (unit/compile-fail tests)
- examples (sample apps per database backend)
- migrations (default SQL migrations for integration tests)
- xtask (monorepo tooling: lint, tidy, custom scripts)
- Notice each crate has its own Cargo.toml and src/, tests/, or examples/ sub-structure.

##### Additional Insights from README
- Core features: zero-cost Rust query builder, code generation, support for SQL and raw queries.
- Supported backends: Postgres, MySQL, SQLite.
- Diesel_cli leverages `diesel` and `diesel_migrations` to run migrations, generate schemas, and provide REPL-style commands.

- Core Library (crate “diesel”)
- Derive Macros (crate “diesel_derives”)
- Dynamic Schema (crate “diesel_dynamic_schema”)
- Migrations Engine (crate “diesel_migrations” + migrations_macros)
- CLI Tool (crate “diesel_cli”)
- Benchmarks (crate “diesel_bench”)
- Test Suites (crates “diesel_tests”, “diesel_compile_tests”)
- Examples (folder “examples”)
- Monorepo Utilities (crate “xtask”)
- External Systems: Rust/Cargo, Database Backends (Postgres, MySQL, SQLite)

- diesel_derives → diesel (codegen expands into core types)
- diesel_dynamic_schema → diesel (builds dynamic queries on core API)
- diesel_migrations → diesel (migration runner uses core connection)
- diesel_migrations_macros → diesel_migrations (embed migrations into binaries)
- diesel_cli → diesel + diesel_migrations + diesel_dynamic_schema (CLI orchestrates core query builder + migrations)
- diesel_bench → diesel (benchmarks core performance)
- diesel_tests/diesel_compile_tests → diesel + derive crates (validate core and derive behavior)
- examples → diesel, diesel_migrations (sample usage against real DBs)
- xtask → workspace crates (runs linting, formatting, releases)
- All core-using components ↔ external DB backends (connections, SQL execution)

c. Architectural Patterns & Principles
- Modular workspace: each feature in its own crate, enabling optional feature flags and independent release cycles.
- Dependency inversion: high-level crates (cli, benches) depend on core abstractions (ConnectionPool, QueryFragment).
- Code generation: derive macros decouple from core query logic, implemented in diesel_derives.
- Embedded DSL: migrations_macros embed filesystem migrations into Rust code.
- Test harness: separate compile_fail and runtime tests ensure both type-level safety and runtime correctness.

d. Key Technologies
- Rust/Cargo workspace
- Procedural macros (syn, quote) in diesel_derives & migrations_macros
- r2d2 connection pooling
- SQL backends (Postgres via tokio_postgres, MySQL via mysql_async, SQLite via rusqlite)
- CI/CD workflows (.github/workflows/*.yml)
- xtask for custom tooling

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Modules
    subgraph "Core Modules"
        CORE["diesel"]:::core
        DERIVE["diesel_derives"]:::macro
        DYN["diesel_dynamic_schema"]:::core
    end

    %% Migrations Engine
    subgraph "Migrations Engine"
        MIG["diesel_migrations"]:::macro
        MAC["diesel_migrations_macros"]:::macro
    end

    %% Tooling & Testing
    subgraph "Tooling & Testing"
        CLI["diesel_cli"]:::tool
        BENCH["diesel_bench"]:::tool
        TESTR["diesel_tests"]:::tool
        TESTC["diesel_compile_tests"]:::tool
        XTASK["xtask"]:::tool
        EXAMPLE["examples"]:::tool
    end

    %% External Databases
    subgraph "External Systems"
        PG["Postgres"]:::db
        MY["MySQL"]:::db
        SQ["SQLite"]:::db
    end

    %% Dependencies (compile-time)
    DERIVE -->|compile-time| CORE
    DYN -->|compile-time| CORE
    MIG -->|compile-time| CORE
    MAC -->|compile-time| MIG
    CLI -->|compile-time| CORE
    CLI -->|compile-time| MIG
    CLI -->|compile-time| DYN
    BENCH -->|compile-time| CORE
    TESTR -->|compile-time| CORE
    TESTR -->|compile-time| DERIVE
    TESTC -->|compile-time| CORE
    TESTC -->|compile-time| DERIVE
    EXAMPLE -->|compile-time| CORE
    EXAMPLE -->|compile-time| MIG
    XTASK -->|compile-time| CORE
    XTASK -->|compile-time| DERIVE
    XTASK -->|compile-time| DYN
    XTASK -->|compile-time| MIG
    XTASK -->|compile-time| MAC
    XTASK -->|compile-time| CLI
    XTASK -->|compile-time| BENCH
    XTASK -->|compile-time| TESTR
    XTASK -->|compile-time| TESTC
    XTASK -->|compile-time| EXAMPLE

    %% Runtime interactions (DB I/O)
    CLI -.->|runtime| PG
    CLI -.->|runtime| MY
    CLI -.->|runtime| SQ
    BENCH -.->|runtime| PG
    BENCH -.->|runtime| MY
    BENCH -.->|runtime| SQ
    EXAMPLE -.->|runtime| PG
    EXAMPLE -.->|runtime| MY
    EXAMPLE -.->|runtime| SQ

    %% Click Events
    click CORE "https://github.com/diesel-rs/diesel/tree/master/diesel/src/"
    click DERIVE "https://github.com/diesel-rs/diesel/tree/master/diesel_derives/src/"
    click DYN "https://github.com/diesel-rs/diesel/tree/master/diesel_dynamic_schema/src/"
    click MIG "https://github.com/diesel-rs/diesel/tree/master/diesel_migrations/src/"
    click MAC "https://github.com/diesel-rs/diesel/tree/master/diesel_migrations/migrations_macros/src/"
    click CLI "https://github.com/diesel-rs/diesel/tree/master/diesel_cli/src/"
    click BENCH "https://github.com/diesel-rs/diesel/tree/master/diesel_bench/benches/"
    click TESTR "https://github.com/diesel-rs/diesel/tree/master/diesel_tests/tests/"
    click TESTC "https://github.com/diesel-rs/diesel/tree/master/diesel_compile_tests/tests/fail/"
    click EXAMPLE "https://github.com/diesel-rs/diesel/tree/master/examples/"
    click XTASK "https://github.com/diesel-rs/diesel/tree/master/xtask/src/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef tool fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef macro fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef db fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
