bisql

# bisql bisql est un moteur de templates SQL bidirectionnel pour Go. Il permet d'écrire des templates SQL qui sont à la fois des instructions SQL valides (exécutables dans un client SQL) et des générateurs de requêtes paramétrées pour les applications. Les directives sont exprimées sous forme de commentaires SQL, de sorte que le même texte fonctionne dans les deux contextes. ## Fonctionnalités clés - **SQL bidirectionnel** : Les templates sont du SQL valide ; les directives sont des commentaires. Le même texte s'exécute dans un client (avec des valeurs d'exemple) et construit des instructions paramétrées `(SQL, Args)` en Go. - **Modèle explicite** : Pas de suppression implicite de clauses vides ou de connecteurs suspendus. Les auteurs ancrent les fragments dynamiques (par exemple, `1 = 1`) pour un résultat prévisible. - **Directives** : Liaison (`/* expr */littéral`), interpolation littérale (`/*^ expr */littéral`), conditionnels (`/*%if*/`, `/*%elseif*/`, `/*%else*/`, `/*%end*/`), boucles (`/*%for x in xs*/`) et inclusions (`/*%! @include nom */`). - **Inclusion de fragments** : Fragments SQL réutilisables composés via `@include`, résolus à partir de `fs.FS`, de registres en mémoire ou de chargeurs personnalisés. Récursif avec protections contre les cycles et la profondeur. - **Support des dialectes** : Génération de placeholders pour MySQL, SQLite, PostgreSQL, Oracle et SQL Server. Liaison de tableaux pour PostgreSQL. - **Langage d'expressions** : Utilise expr-lang pour les conditions et les itérables, avec prise en charge de la comparaison, des opérations logiques, du chaînage optionnel, de la coalescence nulle, de `in` et de `len`. - **Sûr par conception** : Aucune substitution de texte brut de valeurs arbitraires ; les identifiants dynamiques doivent être autorisés via les branches `/*%if*/`. ## Utilisation Les templates sont des fichiers `.sql`. Analysez-les avec `ParseFile` depuis n'importe quel `fs.FS` (par exemple, embarqué), puis construisez avec une carte de paramètres ou une structure. ```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 paramétré fmt.Println(stmt.Args) // arguments de liaison ``` ## Règles de rédaction - Ancrez les fragments dynamiques (par exemple, `1 = 1` pour les chaînes `AND`, `1 = 0` pour les chaînes `OR`). - Pour les listes, utilisez des connecteurs de tête (`and`/`or`) ou `union all select` à partir d'une graine de zéro ligne pour les listes séparées par des virgules. - Citez les chaînes/identifiants avec le doublement standard SQL ; l'échappement par barre oblique inverse n'est pas reconnu. - Utilisez `/*%! … */` pour les commentaires d'analyseur (supprimés) ou `/** … */` pour les commentaires de bloc ordinaires. ## Structure du paquet - `bisql` : API publique (Parser, Parse, Expand, chargeurs). - `dialect/` : Définitions des dialectes. - `expr/` : Interface d'évaluateur et Scope. - `internal/` : Couche de template et évaluateur par défaut. ## Développement La chaîne d'outils est épinglée dans `mise.toml` ; exécutez `mise run check` pour fmt, build, vet, lint et les tests. Les tests d'intégration avec PostgreSQL nécessitent une balise de build et un DSN. Pour la documentation complète, voir la [Référence Go](https://pkg.go.dev/github.com/mpyw/bisql).