How nzmprlr/sqlpp works
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).