# aaberg/sql2o architecture

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

- Interactive diagram: https://gitdiagram.com/aaberg/sql2o
- Repository: https://github.com/aaberg/sql2o

## Overview

This project is a Java library named sql2o whose purpose is to simplify database interactions by mapping SQL results directly into POJOs. It works much like a lightweight ORM – but without the SQL generation – and is designed to be both easy-to-use and easily extendable with support for different SQL databases through specialized modules.

##### Main Components
- Extensions: Clearly mark an “Extensions” area to represent the points of extension. These modules (located in directories such as extensions/db2, extensions/oracle, extensions/postgres, and extensions/oracle-joda-time) plug into the core via Java’s SPI mechanism (as evidenced by the META-INF/services files) to provide database-specific functionality.

##### Relationships and Interactions
- Data flow paths: for instance, an application using Sql2o sends a query to Sql2o Core; the core then obtains a database connection (through a connection source), executes the query, maps results using converters and result set handlers, and finally returns POJO objects.

##### Architectural Patterns and Design Principles
- Modular Design and Extensibility: The separation of the core functionality from vendor-specific extensions is critical. This plugin-style architecture allows new converters or quirks to be added by simply providing new extension modules.
- Dependency Injection / Service Provider: Note the use of the SPI mechanism on the extensions side, for instance, through the clear presence of META-INF/services configuration files in the project structure.

##### Relevant Technologies and Frameworks
- Java (minimum JDK 7/8 support) is the implementation platform.
- Maven is used for project builds (as visible in the pom.xml files throughout the project).
- GitHub Actions is used for continuous integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level
    Application["Application"]

    %% Core Module Subgraph
    subgraph "Core Module"
        sql2oCore["Sql2o Core"]
        converters["Converters"]
        resultSet["ResultSet Handling"]
        connSources["Connection Sources"]
        quirks["Quirks Handling"]
    end

    %% Extensions Subgraph
    subgraph "Extensions"
        db2["DB2 Module"]
        oracle["Oracle Module"]
        oracleJoda["Oracle Joda-Time Module"]
        postgres["Postgres Module"]
    end

    %% Testing and Build Infrastructure Subgraph
    subgraph "Testing & Build Infrastructure"
        testSuite["Test Suite"]
        ci["CI Pipeline"]
        maven["Maven Config"]
    end

    %% Data Flow from Application to Core
    Application -->|"sendsQuery"| sql2oCore

    %% Core Internal Relationships
    sql2oCore -->|"handles"| converters
    sql2oCore -->|"handles"| resultSet
    sql2oCore -->|"manages"| connSources
    sql2oCore -->|"applies"| quirks

    %% Extensions use SPI mechanism to plug into Core
    db2 -->|"SPI"| sql2oCore
    oracle -->|"SPI"| sql2oCore
    oracleJoda -->|"SPI"| sql2oCore
    postgres -->|"SPI"| sql2oCore

    %% Testing and Build interactions (optional representation)
    sql2oCore ---|"validatedBy"| testSuite
    sql2oCore ---|"builtWith"| maven
    testSuite ---|"triggeredBy"| ci

    %% Click Events
    click sql2oCore "https://github.com/aaberg/sql2o/tree/master/core/src/main/java/org/sql2o"
    click converters "https://github.com/aaberg/sql2o/tree/master/core/src/main/java/org/sql2o/converters"
    click resultSet "https://github.com/aaberg/sql2o/blob/master/core/src/main/java/org/sql2o/DefaultResultSetHandlerFactory.java"
    click connSources "https://github.com/aaberg/sql2o/tree/master/core/src/main/java/org/sql2o/connectionsources"
    click quirks "https://github.com/aaberg/sql2o/tree/master/core/src/main/java/org/sql2o/quirks"
    click db2 "https://github.com/aaberg/sql2o/tree/master/extensions/db2"
    click oracle "https://github.com/aaberg/sql2o/tree/master/extensions/oracle"
    click oracleJoda "https://github.com/aaberg/sql2o/tree/master/extensions/oracle-joda-time"
    click postgres "https://github.com/aaberg/sql2o/tree/master/extensions/postgres"
    click testSuite "https://github.com/aaberg/sql2o/tree/master/core/src/test"
    click ci "https://github.com/aaberg/sql2o/blob/master/.github/workflows/pipeline.yml"
    click maven "https://github.com/aaberg/sql2o/blob/master/pom.xml"

    %% Class Styles
    classDef coreColor fill:#DFF0D8,stroke:#3C763D,stroke-width:2px;
    classDef extensionColor fill:#D9EDF7,stroke:#31708F,stroke-width:2px,stroke-dasharray: 5,5;
    classDef infraColor fill:#FCF8E3,stroke:#8A6D3B,stroke-width:2px;
    classDef appColor fill:#F2DEDE,stroke:#A94442,stroke-width:2px;

    class sql2oCore,converters,resultSet,connSources,quirks coreColor;
    class db2,oracle,oracleJoda,postgres extensionColor;
    class testSuite,ci,maven infraColor;
    class Application appColor;
```
