docs: add documentation and examples for sqlc.narg

Author: skabbes

docs/howto/named_parameters.md

@@ -56,3 +56,36 @@ SET
     END
 RETURNING *;
 ```
+
+## Nullable parameters
+
+sqlc infers the nullability of any specified parameters, and often does exactly
+what you want. If you want finer control over the nullability of your
+parameters, you may use `sql.narg()` (**n**ullable arg) to override the default
+behavior. Using `sql.narg` tells sqlc to ignore whatever nullability it has
+inferred and generate a nullable parameter instead.
+
+.. note::
+   There is no nullable equivalent of the `@` syntax.
+
+Here is an example that uses a single query to allow updating an author's
+name, bio or both.
+
+```sql
+-- name: UpdateAuthor :one
+UPDATE author
+SET
+ name = coalesce(sqlc.narg('name'), name),
+ bio = coalesce(sqlc.narg('bio'), bio)
+WHERE id = sqlc.arg('id');
+```
+
+The following code is generated:
+
+```go
+type UpdateAuthorParams struct {
+	Name sql.NullString
+	Bio  sql.NullString
+	ID   int64
+}
+```

examples/authors/mysql/query.sql

@@ -10,9 +10,16 @@ ORDER BY name;
 INSERT INTO authors (
   name, bio
 ) VALUES (
-  ?, ? 
+  ?, ?
 );
 
 /* name: DeleteAuthor :exec */
 DELETE FROM authors
 WHERE id = ?;
+
+/* name: UpdateAuthor :exec */
+UPDATE authors
+SET
+ name = coalesce(sqlc.narg('name'), name),
+ bio = coalesce(sqlc.narg('bio'), bio)
+WHERE id = sqlc.arg('id');

examples/authors/mysql/query.sql.go

@@ -17,3 +17,10 @@ RETURNING *;
 -- name: DeleteAuthor :exec
 DELETE FROM authors
 WHERE id = $1;
+
+-- name: UpdateAuthor :exec
+UPDATE authors
+SET
+ name = coalesce(sqlc.narg('name'), name),
+ bio = coalesce(sqlc.narg('bio'), bio)
+WHERE id = sqlc.arg('id');