fix(docs): Better discussion of type override nuances (#2972)

* fix(docs): Better discussion of type override nuances

* Better defaults

Author: andrewmbenton

docs/howto/overrides.md

@@ -1,13 +1,14 @@
 # Overriding types
 
-The default mapping of PostgreSQL/MySQL types to Go types only uses packages outside
-the standard library when it must.
-
-For example, the `uuid` PostgreSQL type is mapped to `github.com/google/uuid`.
-If a different Go package for UUIDs is required, specify the package in the
-`overrides` array. In this case, I'm going to use the `github.com/gofrs/uuid`
+In many cases it's useful to tell `sqlc` explicitly what Go type you want it to
+use for a query input or output. For instance, a PostgreSQL UUID type will map
+to `UUID` from `github.com/jackc/pgx/pgtype` by default when you use
+`pgx/v5`, but you may want `sqlc` to use `UUID` from `github.com/google/uuid`
 instead.
 
+If you'd like `sqlc` to use a different Go type, specify the package import
+path and type in the `overrides` list.
+
 ```yaml
 version: "2"
 sql:
@@ -17,34 +18,44 @@ sql:
   gen:
     go: 
       package: "authors"
-      out: "postgresql"
+      out: "db"
+      sql_package: "pgx/v5"
       overrides:
         - db_type: "uuid"
-          go_type: "github.com/gofrs/uuid.UUID"
+          go_type:
+            import: "github.com/google/uuid"
+            type: "UUID"
 ```
 
-Each mapping of the `overrides` collection has the following keys:
+## The `overrides` list
+
+Each element in the `overrides` list has the following keys:
 
 - `db_type`:
-  - The PostgreSQL or MySQL type to override. Find the full list of supported types in [postgresql_type.go](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/postgresql_type.go#L12) or [mysql_type.go](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/mysql_type.go#L12). Note that for Postgres you must use the pg_catalog prefixed names where available. Can't be used if the `column` key is defined.
+  - A database type to override. Find the full list of supported types in [postgresql_type.go](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/postgresql_type.go#L12) or [mysql_type.go](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/mysql_type.go#L12). Note that for Postgres you must use pg_catalog-prefixed names where available. And note that `db_type` and `column` are mutually exclusive.
 - `column`:
-  - In case the type overriding should be done on specific a column of a table instead of a type. `column` should be of the form `table.column` but you can be even more specific by specifying `schema.table.column` or `catalog.schema.table.column`. Can't be used if the `db_type` key is defined.
+  - A column name to override. The value should be of the form `table.column` but you can also specify `schema.table.column` or `catalog.schema.table.column`. Note that `column` and `db_type` are mutually exclusive.
 - `go_type`:
-  - A fully qualified name to a Go type to use in the generated code.
+  - The fully-qualified name of a Go type to use in generated code. This is usually a string but can also be [a map](#the-go_type-map) for more complex configurations.
 - `go_struct_tag`:
-  - A reflect-style struct tag to use in the generated code, e.g. `a:"b" x:"y,z"`.
-    If you want general json/db tags for all fields, use `emit_db_tags` and/or `emit_json_tags` instead.
+  - A reflect-style struct tag to use in generated code, e.g. `a:"b" x:"y,z"`.
+    If you want `json` or `db` tags for all fields, use `emit_json_tags` or `emit_db_tags` instead.
 - `nullable`:
-  - If `true`, use this type when a column is nullable. Defaults to `false`.
+  - If `true`, sqlc will apply this override when a column is nullable.
+    Otherwise `sqlc` will apply this override when a column is non-nullable.
+    Note that this has no effect on `column` overrides. Defaults to `false`.
 
 Note that a single `db_type` override configuration applies to either nullable or non-nullable
-columns, but not both. If you want a single `go_type` to override in both cases, you'll
-need to specify two overrides.
+columns, but not both. If you want the same Go type to override in both cases, you'll
+need to configure two overrides.
+
+When generating code, entries using the `column` key will always take precedence over
+entries using the `db_type` key.
 
-When generating code, entries using the `column` key will always have preference over
-entries using the `db_type` key in order to generate the struct.
+### The `go_type` map
 
-For more complicated import paths, the `go_type` can also be an object with the following keys:
+Some overrides may require more detailed configuration. If necessary, `go_type`
+can be a map with the following keys:
 
 - `import`:
   - The import path for the package where the type is defined.
@@ -53,9 +64,9 @@ For more complicated import paths, the `go_type` can also be an object with the
 - `type`:
   - The type name itself, without any package prefix.
 - `pointer`:
-  - If set to `true`, generated code will use pointers to the type rather than the type itself.
+  - If `true`, generated code will use a pointer to the type rather than the type itself.
 - `slice`:
-  - If set to `true`, generated code will use a slice of the type rather than the type itself.
+  - If `true`, generated code will use a slice of the type rather than the type itself.
 
 An example:
 
@@ -68,12 +79,13 @@ sql:
   gen:
     go: 
       package: "authors"
-      out: "postgresql"
+      out: "db"
+      sql_package: "pgx/v5"
       overrides:
         - db_type: "uuid"
           go_type:
             import: "a/b/v2"
             package: "b"
             type: "MyType"
             pointer: true
-```
+```