bisql

# bisql bisql é um mecanismo de template SQL bidirecional para Go. Ele permite escrever templates SQL que são simultaneamente declarações SQL válidas (executáveis em um cliente SQL) e construtores de consultas parametrizadas para aplicações. As diretivas são expressas como comentários SQL, então o mesmo texto funciona em ambos os contextos. ## Principais Recursos - **SQL bidirecional**: Templates são SQL válido; diretivas são comentários. O mesmo texto é executado em um cliente (com valores de exemplo) e constrói declarações parametrizadas `(SQL, Args)` em Go. - **Modelo explícito**: Sem remoção implícita de cláusulas vazias ou conectores soltos. Autores ancoram fragmentos dinâmicos (ex.: `1 = 1`) para saída previsível. - **Diretivas**: Bind (`/* expr */literal`), interpolação literal (`/*^ expr */literal`), condicionais (`/*%if*/`, `/*%elseif*/`, `/*%else*/`, `/*%end*/`), loops (`/*%for x in xs*/`) e includes (`/*%! @include name */`). - **Inclusão de fragmentos**: Fragmentos SQL reutilizáveis compostos via `@include`, resolvidos de `fs.FS`, registros em memória ou carregadores personalizados. Recursivo com proteções de ciclo/profundidade. - **Suporte a dialetos**: Geração de placeholders para MySQL, SQLite, PostgreSQL, Oracle e SQL Server. Binding de arrays para PostgreSQL. - **Linguagem de expressão**: Usa expr-lang para condições e iteráveis, suportando comparação, operadores lógicos, encadeamento opcional, coalescência nula, `in` e `len`. - **Seguro por design**: Sem substituição de texto bruto de valores arbitrários; identificadores dinâmicos devem ser permitidos via ramificações `/*%if*/`. ## Uso Templates são arquivos `.sql`. Analise com `ParseFile` de qualquer `fs.FS` (ex.: embutido) e depois construa com um mapa de parâmetros ou 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) // SQL parametrizado fmt.Println(stmt.Args) // argumentos de bind ``` ## Regras de Autoria - Ancora fragmentos dinâmicos (ex.: `1 = 1` para cadeias `AND`, `1 = 0` para cadeias `OR`). - Para listas, use conectores iniciais (`and`/`or`) ou `union all select` a partir de uma semente de zero linhas para listas separadas por vírgulas. - Cite strings/identificadores com duplicação padrão SQL; escaping com barra invertida não é reconhecido. - Use `/*%! … */` para comentários de parser (removidos) ou `/** … */` para comentários de bloco comuns. ## Estrutura do Pacote - `bisql`: API pública (Parser, Parse, Expand, loaders). - `dialect/`: Definições de dialetos. - `expr/`: Interface de avaliador e Scope. - `internal/`: Camada de template e avaliador padrão. ## Desenvolvimento Toolchain fixado em `mise.toml`; execute `mise run check` para fmt, build, vet, lint e testes. Testes de integração com PostgreSQL exigem uma tag de build e DSN. Para documentação completa, veja a [Referência Go](https://pkg.go.dev/github.com/mpyw/bisql).