How insei/gerpo works
Project type and purpose
• Type: Go library / open-source toolkit for data repository abstraction
• Purpose: Provide a generic, builder-based repository API that generates SQL, executes it via interchangeable adapters, and returns typed entities with optional caching/logging
File structure
• Top-level modules:
– builder.go / builder_test.go: entry point for NewBuilder[T]()
– column/: ColumnBuilder and naming/options for mapping struct fields→SQL columns
– query/: User-facing query builders and internal LINQ-style API
– sqlstmt/: SQL statement generator & sub-packages (sqlpart)
– executor/: Core executor, cache layer, adapters (databasesql, pgx4, pgx5, placeholder)
– virtual/: Virtual field (calculated columns) builder
– logger/: Pluggable logging interface
– examples/, tests/: usage examples and integration tests
README for architecture insights
• Main components described under “Documentation”:
– repository (wires together sqlstmt, query, executor; handles hooks/callbacks)
– query (user API & linq internals)
– sqlstmt (SQL generator)
– executor (executes SQL & maps rows→entities)
• Features: adapter pattern for DB drivers, optional cache in executor, column & soft-delete builders
Main components & their relationships
a. Configuration layer (Builder):
• NewBuilder[T]()
• ColumnBuilder[T], VirtualBuilder[T], SoftDeletionBuilder[T]
• Builds a Repository[T] instance bundling table, columns, hooks, error transformers
b. Query layer:
• Per-request GetFirstHelper, GetListHelper, etc.
• Uses query.Linq API to express WHERE, ORDER, GROUP, JOIN
c. SQL generation layer:
• sqlstmt package: count, select, insert, update, delete generators
• sqlpart sub-package builds individual SQL clauses
d. Execution layer:
• Executor core: receives SQL + args, maps results → T
• Cache middleware: context-based cache bundle
• Adapters:
– databasesql (database/sql)
– pgx4, pgx5 (Postgres)
– placeholder (tests/dry run)
e. External services:
• Relational database (Postgres, MySQL, etc.)
• Optional external cache (e.g., Redis)
1. Client Code calls methods on Repository[T]
2. Repository hands parameters → Query Builder (GetList, GetFirst, Insert, Update, Delete)
3. Query Builder emits logical filters/orders → sqlstmt generators → raw SQL + args
4. SQL + args passed into Executor
– Executor invokes Cache (optional)
– On cache miss, Executor dispatches to chosen Adapter
– Adapter uses underlying DB driver to send SQL → Database
– Rows returned → Adapter → Executor maps → []T or T
– Executor stores result in Cache (if configured)
5. Mapped entities returned to Client Code
Architectural patterns & principles
• Builder Pattern: repository, column, query, virtual, soft-delete builders
• Adapter Pattern: pluggable DB drivers under executor/adapters
• Separation of Concerns:
– Mapping (column, virtual)
– Query construction (query, linq)
– SQL generation (sqlstmt)
– Execution & mapping (executor + adapters)
– Cross-cutting: caching, logging, error transformation
• Generics for type safety: Repository[T], builders, helpers
• Core modules and their extension points:
– Where to drop in new adapters (executor/adapters)
– How to add custom cache engines (executor/cache)
– Column/virtual builders for mapping fields
• External integration: DB drivers, Redis, logging backends