I thought I had finished the docs for sql() usage and template strings, but I see they're incomplete.

I think at the very start it would be great with a completely basic description of how the tagged template sql fn are to be used.

Any raw value inside a template string will be replaced with $n and sent as a parameter to postgresql inferring the correct type. If a value needs to be passed directly in the query sql(value) is to be used which ensures escaping happens properly. It also has overloads to expand the most common scenarios in the correct context.

Eg: sql({ a: 'first', b: new Date() })

• in insert context it will expand to (a, b) values ($1, $2)
• in update / where context it will expand to a = $1, b = $2
• in select context it will expand to $1 as a, $2 as b
  and $1 and $2 will be sent as parameters with correct types (string, timestamp) to postgres

As extra help you can supply an array of objects to insert multiple rows in insert context, and also extra arguments to only pluck specific columns from the object. (encouraged for safety).