# syncpk99/csvq-driver architecture

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

- Interactive diagram: https://gitdiagram.com/syncpk99/csvq-driver
- Repository: https://github.com/syncpk99/csvq-driver

## Overview

##### Project type and purpose
- Type: A Go “database/sql” driver (adapter) for the csvq query engine.
- Purpose: Allow Go programs to run csvq statements against CSV (and other supported) files via the standard `database/sql` API.

##### File structure
Top-level Go source files / subcomponents (all under the root package):
- driver.go: implements `driver.Driver` interface (entry point).
- conn.go / session.go: implements connection and session lifecycle.
- stmt.go: implements `driver.Stmt` (prepared statements).
- tx.go: implements `driver.Tx` (transactions).
- rows.go / result.go: implements `driver.Rows` / collecting result sets.
- types.go / value_converter.go: type‐mapping between Go types and CSVQ data types.
- _test.go files: unit tests for each component.
example/: two sample Go programs illustrating:
- csvq-driver-example.go (basic query/exec usage)
- csvq-replace-io-example.go (overriding stdin/stdout for custom IO)
Config/build: go.mod, go.sum, .github workflows.

##### README for additional insights
- Shows use cases: QueryRowContext, Exec, Prepared Statements, Transaction limitations.
- Describes “Replace I/O” functionality (adapter points).
- Highlights dependency on “github.com/mithrandie/csvq/lib/query” – the core engine.

##### Main components & relationships
a. Application Layer (your Go code)
– Calls `sql.Open("csvq", dsn)` → obtains *sql.DB
– Issues `db.QueryContext`, `db.ExecContext`, etc.
b. database/sql package (std lib)
– Manages pooling, abstract interfaces (Driver → Conn → Stmt → Tx → Rows).
c. csvq-driver package
– Implements the adapter interfaces:
- Driver (driver.go)
- Conn & Session (conn.go, session.go)
- Stmt (stmt.go)
- Tx (tx.go)
- Rows/Result (rows.go, result.go)
- Value conversion (types.go, value_converter.go)
– Parses DSN, maintains session config (time zone, format, ANSI quotes).
– Delegates execution to csvq engine via `query` package calls.
– Offers I/O replacement via `SetStdin`, `SetStdout`, `SetOutFile`.
d. csvq/lib/query engine
– Parses SQL statements, executes against CSV files, returns result sets.
– Reads/writes via provided IO interfaces or default os.Stdin/os.Stdout.
e. Data store (file system)
– CSV (and other supported) files in the directory specified by the DSN.

##### Architectural patterns & design principles
- Adapter pattern: csvq-driver adapts Go’s database/sql interface to the csvq engine’s API.
- Separation of concerns:
– Driver layer (conn/stmt/tx/rows) vs. value-mapping layer (types/value_converter)
– Examples folder isolated from core library code.
- Composition over inheritance: interfaces wired together at runtime by database/sql.
- Extensibility hooks: IO replacement functions (plug custom Readers/Writers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Example Programs Layer
    subgraph "Example Programs"
        direction TB
        BasicExample["Basic Query/Exec Usage"]:::example
        IOExample["I/O Replacement Usage"]:::example
    end

    %% Application Layer
    Application["Go Application"]:::application

    %% Standard Library Layer
    DBSQL["database/sql (stdlib)"]:::external

    %% csvq-driver Layer
    subgraph "csvq-driver" 
        direction TB
        Init["Driver Init (DSN Parsing)"]:::driver
        Driver["Driver"]:::driver
        Conn["Conn"]:::driver
        Session["Session"]:::driver
        Stmt["Stmt"]:::driver
        Tx["Tx"]:::driver
        Rows["Rows"]:::driver
        Result["Result"]:::driver
        Types["Types"]:::driver
        ValueConverter["ValueConverter"]:::driver
    end

    %% Core Engine Layer
    QueryEngine["csvq/lib/query Engine"]:::external

    %% File System Layer
    FileSystem["File System (CSV Storage)"]:::fs

    %% Module Config Layer
    subgraph "Module Configuration"
        direction TB
        GoMod["go.mod"]:::config
        GoSum["go.sum"]:::config
    end

    %% Relationships
    BasicExample -->|"uses"| Application
    IOExample -->|"uses"| Application
    Application -->|"sql.Open()"| DBSQL
    DBSQL -->|"Driver.Open()"| Init
    Init -->|"returns Driver"| Driver
    Driver -->|"Conn()"| Conn
    Conn -->|"new Session()"| Session
    Session -->|"Prepare() / Exec() / Begin()"| Stmt
    Session -->|"Begin()"| Tx
    Stmt -->|"QueryContext() / ExecContext()"| Rows
    Stmt -->|"Exec()"| Result
    Tx -->|"Commit()/Rollback()"| Result
    Rows -->|"Scan()"| Application
    Result -->|"LastInsertId()/RowsAffected()"| Application
    Driver -->|"delegates to"| QueryEngine
    Conn -->|"delegates to"| QueryEngine
    Session -->|"delegates to"| QueryEngine
    Stmt -->|"query.Execute()"| QueryEngine
    Tx -->|"query.Execute()"| QueryEngine
    QueryEngine -->|"read/write CSV"| FileSystem

    %% Extensibility
    Session -->|"SetStdin/SetStdout/SetOutFile"| Application

    %% Module Config to driver
    GoMod -->|"module import"| Driver
    GoSum -->|"dependency lock"| Driver

    %% Click Events
    click Driver "https://github.com/syncpk99/csvq-driver/blob/master/driver.go"
    click Conn "https://github.com/syncpk99/csvq-driver/blob/master/conn.go"
    click Session "https://github.com/syncpk99/csvq-driver/blob/master/session.go"
    click Stmt "https://github.com/syncpk99/csvq-driver/blob/master/stmt.go"
    click Tx "https://github.com/syncpk99/csvq-driver/blob/master/tx.go"
    click Rows "https://github.com/syncpk99/csvq-driver/blob/master/rows.go"
    click Result "https://github.com/syncpk99/csvq-driver/blob/master/result.go"
    click Types "https://github.com/syncpk99/csvq-driver/blob/master/types.go"
    click ValueConverter "https://github.com/syncpk99/csvq-driver/blob/master/value_converter.go"
    click BasicExample "https://github.com/syncpk99/csvq-driver/blob/master/example/csvq-driver/csvq-driver-example.go"
    click IOExample "https://github.com/syncpk99/csvq-driver/blob/master/example/replace-io/csvq-replace-io-example.go"
    click Init "https://github.com/syncpk99/csvq-driver/blob/master/init.go"
    click GoMod "https://github.com/syncpk99/csvq-driver/blob/master/go.mod"
    click GoSum "https://github.com/syncpk99/csvq-driver/blob/master/go.sum"

    %% Styles
    classDef driver fill:#c2f0c2,stroke:#2d862d,stroke-width:1px
    classDef external fill:#c2d9fc,stroke:#0455fa,stroke-width:1px
    classDef fs fill:#e0e0e0,stroke:#6d6d6d,stroke-width:1px
    classDef example fill:#fff2cc,stroke:#e69900,stroke-width:1px
    classDef application fill:#f2f2f2,stroke:#999999,stroke-width:1px
    classDef config fill:#f9e6f9,stroke:#b347b3,stroke-width:1px
```
