Parse and handle additional query metadata via annotations in comments

[andrewmbenton]

What do you want to change?

Kyle and I have been discussing how to add support for more query-specific configuration. The particular need driving this is to have a way to opt individual queries out of sqlc vet rules (which are set globally for a sqlc package). But it would also be nice to provide a common configuration syntax and behavior for passing query-specific metadata to plugins (e.g. as requested here: #2270).

The proposal is:

In any SQL comment, a line starting with @symbol will have all text following the symbol parsed as yaml. If no text follows the symbol then we infer a boolean true value.

We would then pass that structured data to plugins, as well as make use of it internally.

Here's a hypothetical queries.sql:

-- name: GetAuthor :one
-- @sqlc-vet-disable # implies skip all vet rules
SELECT * FROM authors
WHERE id = $1 LIMIT 1;

-- name: ListAuthors :many
-- @sqlc-vet-disable [foo, bar] # disable the vet rules named foo and bar
-- @plugin-attr {"foo": "bar"} # a k/v map used by some plugin
SELECT * FROM authors
ORDER BY name;

If you have feedback on this please leave a comment. I'd especially like to hear from anyone who's aware of tooling that does something similar with comments in sql files, so that we can avoid inadvertent conflicts.

What database engines need to be changed?

No response

What programming language backends need to be changed?

No response