Tips and FAQ

Tips

Bisql block comment sigils

Bisql reserves five sigils at the start of block comments:

$, ^, !, %, :

1. /*$ */ - bind values (ex. ?)
2. /*^ */ - literal values (ex. 'John')
3. /*! */ - raw values (ex. created_at)
4. /*% */ - control flow (if / for)
5. /*: */ - metadata declarations

Do not use those sigils accidentally at the start of an ordinary SQL block comment. To keep room for future extensions, prefer a space or * when you mean a normal comment:

• /* */
• /** */

FAQ

Why does Bisql not provide a query builder or data mapper?

Starting every data access path from explicit SQL files keeps many things simpler:

• investigating database problems and performance issues
• reviewing SQL with database-focused engineers
• understanding the overall shape of data access in the application

Mixing query builders or data mappers into that model tends to hide information and makes the full data access layer harder to reason about. Queries that begin as “simple enough for a builder” often grow until plain SQL would have been easier to maintain from the start.

Why are namespaces derived from SQL file locations instead of the namespace where (defquery) is written?

Bisql lets SQL file layout define query function layout. That behavior can be surprising at first, but it keeps the mapping simple and explicit. It also keeps the generated query functions colocated with the SQL they come from, which makes the codebase easier to navigate.

Why 2-way SQL? Block-comment-based parameter markers do not look very readable.

The main reason is that the templates remain executable as SQL. That makes them much easier to develop, test, and refine while running the SQL directly. The block-comment-based markers may look unusual at first, but they become natural with use.

If query functions are generated by macros, why does Bisql also generate function namespace files for them?

Generating function namespace files is optional, but it is not only an IDE convenience. Those generated files make query functions easier to require from ordinary application code, while also giving IDEs and linters stable targets for navigation and analysis. That is especially useful when you generate CRUD SQL and want the matching query functions to behave like normal namespaces in the rest of the project.

For example, Bisql can generate a minimal namespace stub like this:

(declare ^{:arglists (quote ([datasource] [datasource template-params]))
           :cardinality :one
           :bisql.define/navigation-stub true
           :doc "This function is generated from SQL: src/sql/postgresql/public/orders/crud.sql:1"}
  insert)

How does the Playground render SQL templates?

Bisql shares the parsing and renderer-plan logic between Clojure and ClojureScript in .cljc. From there, Clojure consumes the result through macro expansion or eval, while ClojureScript renders the same structure through an interpreter. The Playground uses that interpreter path.