bisql

# bisql bisql is a two-way SQL template engine for Go. It lets you write SQL templates that are simultaneously valid SQL statements (executable in a SQL client) and parameterized query builders for applications. Directives are expressed as SQL comments, so the same text works in both contexts. ## Key Features - **Two-way SQL**: Templates are valid SQL; directives are comments. The same text runs in a client (with sample values) and builds parameterized statements `(SQL, Args)` in Go. - **Explicit model**: No implicit removal of empty clauses or dangling connectors. Authors anchor dynamic fragments (e.g., `1 = 1`) for predictable output. - **Directives**: Bind (`/* expr */literal`), literal interpolation (`/*^ expr */literal`), conditionals (`/*%if*/`, `/*%elseif*/`, `/*%else*/`, `/*%end*/`), loops (`/*%for x in xs*/`), and includes (`/*%! @include name */`). - **Fragment inclusion**: Reusable SQL fragments composed via `@include`, resolved from `fs.FS`, in-memory registries, or custom loaders. Recursive with cycle/depth guards. - **Dialect support**: Placeholder generation for MySQL, SQLite, PostgreSQL, Oracle, and SQL Server. Array binding for PostgreSQL. - **Expression language**: Uses expr-lang for conditions and iterables, supporting comparison, logical ops, optional chaining, nil-coalescing, `in`, and `len`. - **Safe by design**: No raw-text substitution of arbitrary values; dynamic identifiers must be whitelisted via `/*%if*/` branches. ## Usage Templates are `.sql` files. Parse with `ParseFile` from any `fs.FS` (e.g., embedded), then build with a parameter map or struct. ```go p := bisql.NewParser(bisql.WithDialect(dialect.PostgreSQL)) tmpl, err := p.ParseFile(sqlFS, "users/search.sql") stmt, err := tmpl.Build(map[string]any{"name": "Alice", "activeOnly": true, "status": "active"}) fmt.Println(stmt.SQL) // parameterized SQL fmt.Println(stmt.Args) // bind arguments ``` ## Authoring Rules - Anchor dynamic fragments (e.g., `1 = 1` for `AND` chains, `1 = 0` for `OR` chains). - For lists, use leading connectors (`and`/`or`) or `union all select` off a zero-row seed for comma lists. - Quote strings/identifiers with SQL-standard doubling; backslash escaping is not recognized. - Use `/*%! … */` for parser comments (removed) or `/** … */` for ordinary block comments. ## Package Layout - `bisql`: Public API (Parser, Parse, Expand, loaders). - `dialect/`: Dialect definitions. - `expr/`: Evaluator interface and Scope. - `internal/`: Template layer and default evaluator. ## Development Toolchain pinned in `mise.toml`; run `mise run check` for fmt, build, vet, lint, and tests. Integration tests with PostgreSQL require a build tag and DSN. For full documentation, see the [Go Reference](https://pkg.go.dev/github.com/mpyw/bisql).