Declarations and Metadata

Bisql supports declaration comments inside SQL files.

These declarations are parsed and returned under :meta.

Syntax

/*:name
<edn-or-text>
*/

Example:

/*:doc
Loads a user by id.
*/
/*:cardinality
:one
*/
SELECT *
FROM users
WHERE id = /*$id*/1

Rendered result:

{:sql "SELECT * FROM users WHERE id = ?"
 :params [42]
 :meta {:doc "Loads a user by id."
        :cardinality :one}}

Common Uses

• documentation
• tags
• cardinality hints
• project-specific metadata

Notes

• duplicate declarations are errors
• declaration bodies are parsed as EDN by default
• :doc also accepts plain text and is trimmed into a string

This metadata is useful both in rendering output and in generated declaration namespaces.

See also:

• Rendering
• Rendering Examples