# jasonshin/sqlx-ts architecture

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

- Interactive diagram: https://gitdiagram.com/jasonshin/sqlx-ts
- Repository: https://github.com/jasonshin/sqlx-ts

## Overview

##### Project’s Main Purpose and Type
- sqlx-ts is a command-line interface (CLI) tool designed for compile-time validation of SQL queries and generation of type-safe TypeScript interfaces from SQL. It is not an ORM; rather, it validates SQL by connecting to a database at compile time and generates types based on the underlying database schema.
- The tool supports both TypeScript and JavaScript environments and operates largely via Rust (with Cargo.toml and src for core logic) while offering integration tests and demo usage through Node.js code and samples.

##### Main Architectural Components
- CLI / Entry Point:
– The main application entry is in src/main.rs, and the CLI logic is also partly contained in src/common/cli.rs.
– This component receives user commands (both via direct CLI invocations and potentially via scripts) to trigger SQL checking and type generation.
- Core Engine / Query Validation:
– Under src/core, you have modules for establishing connections with databases (MySQL and PostgreSQL), executing queries, and preparing SQL statements.
– This module represents the runtime engine that interacts directly with the target databases at compile time for query verification.
- SQL Parser and TypeScript Generator:
– In src/ts_generator, the tool parses SQL, handles annotations, and generates TypeScript types.
– The parser submodules (such as src/ts_generator/sql_parser) transform raw SQL into internal representations that later inform type generation.
- Common Utilities:
– In src/common, utilities for configuration, logging, error handling, and environment variable support exist.
– This layer abstracts cross-cutting concerns that are used by both the CLI and core engine.
- Tests and Demos:
– The tests folder (with various examples checking multiple scenarios) and the samples folder (which provide demo implementations for different use cases) show how integrated testing validates the tool.
– The node directory contains Node.js-specific configurations and scripts (e.g., ESLint and Jest configurations) for the TypeScript/JavaScript side.
- Documentation and Community Support:
– The “book” directory houses the documentation (built with Docusaurus), and the present .github/workflows directory contains CI/CD scripts that integrate tasks like linting, testing, code coverage, and automated releases.
– Extra directories like “playpen” serve as sandbox or demo areas where migrations and demos can be executed.

##### Relationships and Interactions between Components
- The CLI component (via src/main.rs and CLI helpers) acts as the orchestrator. It receives user commands and delegates the work to the core engine to check SQL queries and then to the TypeScript generator.
- The core engine modules (src/core/mysql, src/core/postgres) interact with target databases at compile time to verify the SQL syntax.
- The SQL parser (in src/ts_generator/sql_parser) transforms SQL queries and collaborates with the type generator (src/ts_generator) to produce TypeScript interfaces that the developer can then use.
- Testing and demo examples (tests, samples, playpen) simulate real-world usage and help verify the integration with both the CLI and Node environments.
- CI/CD workflows defined in .github/workflows continuously check the stability of the application across builds, tests, and releases.

##### Down Important Architectural Patterns/Design Principles
- Modular / Layered Architecture: Separation between the CLI frontend, core database query logic, SQL parsing, and type generation.
- Compile-Time Verification: The design leverages compile-time checks (inspired by the sqlx Rust project) to ensure that all SQL queries are valid before being shipped.
- Database Agnostic Handling: Separate modules for MySQL and PostgreSQL indicate a design that isolates database-specific logic.
- Extensive Testing and Documentation: The existence of various test suites and documentation efforts suggests a design that emphasizes maintainability and community contribution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Interface"
        CLI1["Main (src/main.rs)"]:::cli
        CLI2["CLI Helpers (src/common/cli.rs)"]:::cli
    end

    subgraph "Core Query Validator"
        CR["Core Runtime (src/core)"]:::core
        MYSQL["MySQL Module (src/core/mysql)"]:::core
        POSTGRES["Postgres Module (src/core/postgres)"]:::core
    end

    subgraph "SQL Parser & TS Generator"
        TS_GEN["TS Generator (src/ts_generator)"]:::ts
        SQL_PARSER["SQL Parser (src/ts_generator/sql_parser)"]:::ts
        TS_TYPES["TS Types (src/ts_generator/types)"]:::ts
    end

    subgraph "Utilities & Config"
        UTIL["Common Utilities (src/common)"]:::util
    end

    subgraph "Testing & Demos"
        TEST["Tests (tests)"]:::test
        SAMPLES["Samples (samples)"]:::test
        PLAYPEN["Playpen (playpen)"]:::test
        NODE_INT["Node Integration (node)"]:::test
    end

    subgraph "Documentation & CI/CD"
        DOC["Documentation (book)"]:::doc
        CI["CI/CD Pipelines (.github/workflows)"]:::doc
    end

    %% External databases
    MY_SQL_DB["MySQL Database"]:::external
    POSTGRES_DB["PostgreSQL Database"]:::external

    %% Relationships
    CLI1 -->|"triggers"| CR
    CLI2 -->|"triggers"| CR
    CR -->|"executes_query_validation"| MYSQL
    CR -->|"executes_query_validation"| POSTGRES
    MYSQL -->|"connects"| MY_SQL_DB
    POSTGRES -->|"connects"| POSTGRES_DB
    CR -->|"invokes"| TS_GEN
    TS_GEN -->|"parses_SQL"| SQL_PARSER
    TS_GEN -->|"generates_types"| TS_TYPES
    CLI1 -->|"uses"| UTIL
    CR -->|"utilizes"| UTIL
    TEST -->|"tests"| CLI1
    TEST -->|"tests"| TS_GEN
    SAMPLES -->|"demonstrates"| NODE_INT
    DOC -->|"provides_docs_for"| CLI1
    CI -->|"runs_pipelines_for"| TEST

    %% Click Events
    click CLI1 "https://github.com/jasonshin/sqlx-ts/blob/main/src/main.rs"
    click CLI2 "https://github.com/jasonshin/sqlx-ts/blob/main/src/common/cli.rs"
    click CR "https://github.com/jasonshin/sqlx-ts/blob/main/src/core/connection.rs"
    click MYSQL "https://github.com/jasonshin/sqlx-ts/blob/main/src/core/mysql/mod.rs"
    click MYSQL "https://github.com/jasonshin/sqlx-ts/blob/main/src/core/mysql/pool.rs"
    click MYSQL "https://github.com/jasonshin/sqlx-ts/blob/main/src/core/mysql/prepare.rs"
    click POSTGRES "https://github.com/jasonshin/sqlx-ts/blob/main/src/core/postgres/mod.rs"
    click POSTGRES "https://github.com/jasonshin/sqlx-ts/blob/main/src/core/postgres/pool.rs"
    click POSTGRES "https://github.com/jasonshin/sqlx-ts/blob/main/src/core/postgres/prepare.rs"
    click TS_GEN "https://github.com/jasonshin/sqlx-ts/blob/main/src/ts_generator/generator.rs"
    click SQL_PARSER "https://github.com/jasonshin/sqlx-ts/tree/main/src/ts_generator/sql_parser"
    click TS_TYPES "https://github.com/jasonshin/sqlx-ts/blob/main/src/ts_generator/types/ts_query.rs"
    click UTIL "https://github.com/jasonshin/sqlx-ts/blob/main/src/common/config.rs"
    click TEST "https://github.com/jasonshin/sqlx-ts/tree/main/tests"
    click SAMPLES "https://github.com/jasonshin/sqlx-ts/tree/main/samples"
    click PLAYPEN "https://github.com/jasonshin/sqlx-ts/tree/main/playpen"
    click NODE_INT "https://github.com/jasonshin/sqlx-ts/tree/main/node"
    click DOC "https://github.com/jasonshin/sqlx-ts/tree/main/book"
    click CI "https://github.com/jasonshin/sqlx-ts/tree/main/.github/workflows"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef core fill:#A3E4D7,stroke:#1E8449,stroke-width:2px;
    classDef ts fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef util fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef test fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef doc fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
