How syncpk99/csvq-driver works
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).