docs: Add named parameter documentation (#332)

* docs: Add named parameter documentation

* Add named parameters to README

Author: kyleconroy

README.md

@@ -1,13 +1,3 @@
-> 🚨
->
-> sqlc is **new** and under rapid development.
->
-> The code it generates is correct and safe for production use, but there is
-> currently no guarantee of stability or backwards-compatibility of the command
-> line interface, configuration file format or generated code.
->
-> 🚨
-
 # sqlc: A SQL Compiler
 
 > And lo, the Great One looked down upon the people and proclaimed:
@@ -232,6 +222,7 @@ Your favorite PostgreSQL / Go features are supported:
   - [Query annotations](./docs/annotations.md)
   - [Transactions](./docs/transactions.md)
   - [Prepared queries](./docs/prepared_query.md)
+  - [Named parameters](./docs/named_parameters.md)
   - [SELECT](./docs/query_one.md)
   - [NULL](./docs/null.md)
   - [COUNT](./docs/query_count.md)
@@ -420,7 +411,8 @@ Each commit is deployed to the [`devel` channel on Equinox](https://dl.equinox.i
 ## Other Databases and Languages
 
 sqlc currently only supports PostgreSQL / Go. MySQL support has been merged,
-but it's marked as experimental. SQLite and TypeScript support are planned.
+but it's marked as experimental. SQLite, TypeScript, and Kotlin support are
+planned.
 
 | Language     | PostgreSQL       | MySQL            | SQLite           |
 | ------------ |:----------------:|:----------------:|:----------------:|

docs/named_parameters.md

@@ -0,0 +1,58 @@
+# Named parameters
+
+sqlc tried to generate good names for positional parameters, but sometimes it
+lacks enough context. The following SQL generates parameters with less than
+ideal names:
+
+```sql
+-- name: UpsertAuthorName :one
+UPDATE author
+SET
+  name = CASE WHEN $1::bool
+    THEN $2::text
+    ELSE name
+    END
+RETURNING *;
+```
+
+```go
+type UpdateAuthorNameParams struct {
+  Column1         bool           `json:""`
+  Column2_2       string         `json:"_2"`
+}
+```
+
+In these cases, named parameters give you the control over field names on the
+Params struct.
+
+```sql
+-- name: UpsertAuthorName :one
+UPDATE author
+SET
+  name = CASE WHEN sqlc.arg(set_name)::bool
+    THEN sqlc.arg(name)::text
+    ELSE name
+    END
+RETURNING *;
+```
+
+```go
+type UpdateAuthorNameParams struct {
+  SetName         bool           `json:"set_name"`
+  Name            string         `json:"name"`
+}
+```
+
+If the `sqlc.arg()` syntax is too verbose for your taste, you can use the `@`
+operator as a shortcut.
+
+```sql
+-- name: UpsertAuthorName :one
+UPDATE author
+SET
+  name = CASE WHEN @set_name::bool
+    THEN @name::text
+    ELSE name
+    END
+RETURNING *;
+```