Add sqlc templates for arbitrary text substitution (minimal)

[brandur]

This one aims to give us a workable resolution to one of our most common
problems with sqlc. Namely, that although it allows substitution for
parameters that work with a prepared query, it can't replace arbitrary
parts of a SQL query, leading to operations that aren't possible so that
we either don't do them or end up degrading to raw SQL that's only
checked at runtime.

Here, we add a sqlctemplate package that's designed to be run from
inside custom implementations of sqlc's DBTX interface so that it it
runs after sqlc's generated code but before the query goes to Postgres.

In sqlc code, templates look like this:

-- name: JobCountByState :one
SELECT count(*)
FROM /* TEMPLATE: schema */river_job
WHERE state = @state;

The template replacement is modeled as a comment so that it doesn't
interfere with with sqlc's parsing of SQL syntax. The above is valid SQL
with or without the template, but with it, sqlctemplate can add an
arbitrary schema name to the queried table.

It also supports a form of syntax where a value is required for SQL to
be valid. For example, WHERE and ORDER BY clauses both require a
value for them to be valid. Here, a stand in value is provide between
template tags. It's processed by sqlc's parser, but then replace by the
template engine before the SQL is executed:

-- name: JobList :many
SELECT *
FROM river_job
WHERE /* TEMPLATE_BEGIN: where_clause */ 1 /* TEMPLATE_END */
ORDER BY /* TEMPLATE_BEGIN: order_by_clause */ id /* TEMPLATE_END */
LIMIT @max::int;

Template values are injected via context (don't love this, but there's
no other way in getting information down to a layer below DBTX):

ctx = sqlctemplate.WithReplacements(ctx, map[string]sqlctemplate.Replacement{
    "order_by_clause": {Value: params.OrderByClause},
    "where_clause":    {Value: params.WhereClause},
}, params.NamedArgs)

jobs, err := dbsqlc.New().JobList(ctx, e.dbtx, params.Max)

The template engine is written to be root out as many error as possible
by noticing if a template replacement is passed that doesn't have an
equivalent template in SQL, or if a template in SQL is present for which
there's no replacement.

Named args are support in templates similar to how sqlc supports them.
This allows pgx's prepared statement cache to continue to operate as it
did before, thereby keeping everything fast.

Lastly, I should note that templates are meant as a utility of last
resort. All effort should be made to resolve problems via mainstream
sqlc, and only bring in templates when there's no other option.

[brandur]

@bgentry Alright, so this one's the same as #792 except that I'e reverted the changes to job listing + use of injected schema, and added a test suite for the templating package.

If you're okay with it I'd propose:

1. Reviewing and getting this merged.
2. Cut release of River for other packages to use an updated rivershared.
3. In parallel:
   1. Start updating the concurrency query.
   2. I can go back and update JobList based on Add sqlc templates for arbitrary text substitution #792. An explicit schema will be a little more work (all queries would need to be updated), but we could look into that from there.

[bgentry]

Looks great!

[brandur]

Excellent, thanks. Let me get this in and start work on formally moving JobList over.

[bgentry]

Is this actually true @brandur? I have some comments in another branch that I would actually love to be stripped out of the final query, but they're not, regardless of whether they're on a -- or /* */ comment line all by themselves.

[bgentry]

Ah, it seems to only happen when the line doesn't have any leading whitespace, i.e. solely the comment and nothing else (similar to comment lines that denote a query). But if you've indented even a single space, the comment is maintained.

[brandur]

Ah yeah, sounds about right. TBH, I find the behavior kind of confusing, and especially given use of prepared statements with pgx, I doubt the comment stripping is really doing that much perf wise and it probably would've been better if they kept everything in.

Here's the sqlc issue on the subject FWIW. No activity in a while:

sqlc-dev/sqlc#2207