# nzmprlr/sqlpp architecture

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

- Interactive diagram: https://gitdiagram.com/nzmprlr/sqlpp
- Repository: https://github.com/nzmprlr/sqlpp

## Overview

##### Main Components
- Library API – This is the primary entry point where users create connection wrappers. There are two distinct components here:
– MySQL Wrapper (see mysql.go)
– PostgreSQL Wrapper (see sqlpp.go)
- Query Transformation Module – This is the core logic that inspects the query and cached prepared statements and transforms queries (e.g., replaces “in (?)” with “in (?,?)” or with positional arguments for PostgreSQL).
- Underlying Database Connection – This is the raw SQL connection (using Go’s sql.Open) that the wrappers utilize for communication with the actual database.
- Testing & Validation – Represented by unit test files (mysql_test.go, sqlpp_test.go) that verify the behavior of the transformation logic and connection wrappers.
- Configuration & Build System – Files like go.mod, go.sum, and CI workflows (in .github/workflows/go.yml) indicate dependency management and continuous integration, though they are auxiliary to the core architecture.

##### Relationships and Interactions
- The client (application code) calls the sqlpp library API via either NewMySQL or NewPostgreSQL functions.
- The library receives the SQL query along with “in (?)” placeholders and a set of parameters (which may include arrays).
- The Query Transformation Module processes the query:
– Analyzes the input query.
– Transforms the placeholders to the correct format (MySQL: using “?”; PostgreSQL: using positional "$" placeholders).
– Re-maps the arguments accordingly.
- Once transformed, the library forwards the query to the underlying database connection (using Go’s standard database/sql package).
- The query results are then returned via callback functions provided by the caller.
- The testing components simulate various scenarios to ensure correctness.

##### Architectural Patterns and Design Principles
- Separation of Concerns – The library clearly separates query transformation logic from the underlying database connection handling.
- Modularity – Different files and modules handle database-specific differences (MySQL vs PostgreSQL) which makes the design extensible.
- Abstraction – The library abstracts away the complexities of query transformations and connection management, providing a clean interface to the user.
- Integration with Go’s standard library – The design leverages Go’s native SQL package and standard build and dependency management tools.

- Components:
– Client Application (External Call)
– sqlpp Library API (with branches for MySQL and PostgreSQL wrappers)
– Query Transformation Module (logic for expanding placeholders)
– Underlying SQL Connection (standard database/sql in Go)
– Testing/Validation Module (unit tests reference)
– CI/CD and Configuration (optional, as they help understand dependency management and build processes)
- Interactions:
– Show the flow from the API into the Query Transformation Module.
– Indicate the flow of the transformed query to the Underlying SQL Connection.
– Emphasize where feedback or results are sent back from the database to the client.
- Design Details:
– Use clear labels (e.g., “MySQL Wrapper”, “PostgreSQL Wrapper”, “Transform Query”, “Execute Query”).
– Use annotations to denote the transformation differences (e.g., “? vs. $ placeholders”).
– Optionally, indicate external dependencies (Go’s sql package, CI/CD pipeline).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client / Application Code"]:::client
    API["sqlpp Library API"]:::api

    Client -->|"calls"| API

    subgraph "Library API"
        direction TB
        MySQLWrapper["MySQL Wrapper"]:::wrapper
        PostgreSQLWrapper["PostgreSQL Wrapper"]:::wrapper
    end

    API --> MySQLWrapper
    API --> PostgreSQLWrapper

    MySQLWrapper -->|"TransformQuery"| UnderlyingSQL["Underlying SQL Connection (database/sql)"]:::db
    PostgreSQLWrapper -->|"TransformQuery"| UnderlyingSQL
    UnderlyingSQL -->|"ReturnResults"| API
    API -->|"ReturnResults"| Client

    subgraph "Testing & Validation Module"
        direction TB
        MySQLTest["MySQL Tests"]:::test
        PostgreSQLTest["PostgreSQL Tests"]:::test
    end

    MySQLTest ---|"validates"| MySQLWrapper
    PostgreSQLTest ---|"validates"| PostgreSQLWrapper

    subgraph "Configuration & Build System"
        direction TB
        GoMod["go.mod"]:::config
        GoSum["go.sum"]:::config
        CI["CI Workflow (.github/workflows/go.yml)"]:::config
    end

    CI ---|"configures"| API
    GoMod ---|"definesDeps"| API
    GoSum ---|"definesDeps"| API

    click MySQLWrapper "https://github.com/nzmprlr/sqlpp/blob/main/mysql.go"
    click PostgreSQLWrapper "https://github.com/nzmprlr/sqlpp/blob/main/sqlpp.go"
    click MySQLTest "https://github.com/nzmprlr/sqlpp/blob/main/mysql_test.go"
    click PostgreSQLTest "https://github.com/nzmprlr/sqlpp/blob/main/sqlpp_test.go"
    click GoMod "https://github.com/nzmprlr/sqlpp/blob/main/go.mod"
    click GoSum "https://github.com/nzmprlr/sqlpp/blob/main/go.sum"
    click CI "https://github.com/nzmprlr/sqlpp/blob/main/.github/workflows/go.yml"

    classDef client fill:#ffdead,stroke:#333,stroke-width:2px
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:2px
    classDef wrapper fill:#87CEFA,stroke:#333,stroke-width:2px
    classDef db fill:#90EE90,stroke:#333,stroke-width:2px
    classDef test fill:#FFE4B5,stroke:#333,stroke-width:2px
    classDef config fill:#DDA0DD,stroke:#333,stroke-width:2px
```
