docs: clean up and add to docs regarding type overrides (#4060)

Author: andrewmbenton

docs/howto/overrides.md

@@ -1,13 +1,20 @@
 # Overriding types
 
+.. note:: Type overrides and field renaming are only fully-supported for Go.
+
 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.
+use for a query input or output. For instance, by default when you use
+`pgx/v5`, `sqlc` will map a PostgreSQL UUID type to `UUID` from `github.com/jackc/pgx/pgtype`.
+But you may want `sqlc` to use `UUID` from `github.com/google/uuid` instead.
+
+To tell `sqlc` to use a different Go type, add an entry to the `overrides` list in your
+configuration.
 
-If you'd like `sqlc` to use a different Go type, specify the package import
-path and type in the `overrides` list.
+`sqlc` offers two kinds of Go type overrides:
+* `db_type` overrides, which override the Go type for a specific database type.
+* `column` overrides, which override the Go type for a column or columns by name.
+
+Here's an example including one of each kind:
 
 ```yaml
 version: "2"
@@ -22,11 +29,19 @@ sql:
       sql_package: "pgx/v5"
       overrides:
         - db_type: "uuid"
+          nullable: true
           go_type:
             import: "github.com/google/uuid"
             type: "UUID"
+        - column: "users.birthday"
+          go_type: "time.Time"
 ```
 
+.. tip::
+  A single `db_type` override configuration applies to either nullable or non-nullable
+  columns, but not both. If you want the same Go type to override regardless of
+  nullability, you'll need to configure two overrides: one with `nullable: true` and one without.
+
 ## The `overrides` list
 
 Each element in the `overrides` list has the following keys:
@@ -39,21 +54,23 @@ Each element in the `overrides` list has the following keys:
   - 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 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.
+    If you want `json` or `db` tags for all fields, configure `emit_json_tags` or `emit_db_tags` instead.
 - `unsigned`:
-  - If `true`, sqlc will apply this override when a numeric db_type is unsigned.
-    Note that this has no effect on `column` overrides. Defaults to `false`.
+  - If `true`, sqlc will apply this override when a numeric column is unsigned.
+    Note that this only applies to `db_type` overrides and has no effect on `column` overrides.
+    Defaults to `false`.
 - `nullable`:
   - 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 this only applies to `db_type` overrides and 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 the same Go type to override in both cases, you'll
-need to configure two overrides.
+.. tip::
+  A single `db_type` override configuration applies to either nullable or non-nullable
+  columns, but not both. If you want the same Go type to override regardless of nullability, you'll
+  need to configure two overrides: one with `nullable: true` and one without.
 
-When generating code, entries using the `column` key will always take precedence over
-entries using the `db_type` key.
+.. note:: When generating code, `column` override configurations take precedence over `db_type` configurations.
 
 ### The `go_type` map
 
@@ -80,7 +97,7 @@ sql:
   queries: "postgresql/query.sql"
   engine: "postgresql"
   gen:
-    go: 
+    go:
       package: "authors"
       out: "db"
       sql_package: "pgx/v5"
@@ -92,3 +109,74 @@ sql:
             type: "MyType"
             pointer: true
 ```
+
+## Global overrides
+
+To override types in all packages that `sqlc` generates, add an override
+configuration to the top-level `overrides` section of your `sqlc` config:
+
+```yaml
+version: "2"
+overrides:
+  go:
+    overrides:
+      - db_type: "pg_catalog.timestamptz"
+        nullable: true
+        engine: "postgresql"
+        go_type:
+          import: "gopkg.in/guregu/null.v4"
+          package: "null"
+          type: "Time"
+sql:
+- schema: "service1/schema.sql"
+  queries: "service1/query.sql"
+  engine: "postgresql"
+  gen:
+    go: 
+      package: "service1"
+      out: "service1"
+- schema: "service2/schema.sql"
+  queries: "service2/query.sql"
+  engine: "postgresql"
+  gen:
+    go:
+      package: "service2"
+      out: "service2"
+```
+
+Using this configuration, whenever there is a nullable `timestamp with time zone`
+column in a Postgres table, `sqlc` will generate Go code using `null.Time`.
+
+Note that the mapping for global type overrides has a field called `engine` that
+is absent in per-package type overrides. This field is only used when there are
+multiple `sql` sections using different engines. If you're only generating code
+for a single database engine you can omit it.
+
+#### Version 1 configuration
+
+If you are using the older version 1 of the `sqlc` configuration format, override
+configurations themselves are unchanged but are nested differently.
+
+Per-package configurations are nested under the `overrides` key within an item
+in the `packages` list:
+
+```yaml
+version: "1"
+packages:
+  - name: "db"
+    path: "internal/db"
+    queries: "./sql/query/"
+    schema: "./sql/schema/"
+    engine: "postgresql"
+    overrides: [...]
+```
+
+And global configurations are nested under the top-level `overrides` key:
+
+```yaml
+version: "1"
+packages: [...]
+overrides:
+  - db_type: "uuid"
+    go_type: "github.com/gofrs/uuid.UUID"
+```

docs/reference/config.md

@@ -194,36 +194,11 @@ The `gen` mapping supports the following keys:
 - `rename`:
   - Customize the name of generated struct fields. See [Renaming fields](../howto/rename.md) for usage information.
 - `overrides`:
-  - It is a collection of definitions that dictates which types are used to map a database types.
+  - A collection of configurations to override sqlc's default Go type choices. See [Overriding types](../howto/overrides.md) for usage information.
 
 ##### overrides
 
-See [Overriding types](../howto/overrides.md) for an in-depth guide to using type overrides. Each mapping of the `overrides` collection 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.
-- `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.
-- `go_type`:
-  - A fully qualified name to a Go type to use in the generated code.
-- `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.
-- `nullable`:
-  - If `true`, use this type when a column is nullable. Defaults to `false`.
-
-For more complicated import paths, the `go_type` can also be an object with the following keys:
-
-- `import`:
-  - The import path for the package where the type is defined.
-- `package`:
-  - The package name where the type is defined. This should only be necessary when your import path doesn't end with the desired package name.
-- `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.
-- `slice`:
-  - If set to `true`, generated code will use a slice of the type rather than the type itself.
+See [Overriding types](../howto/overrides.md) for an in-depth guide to using type overrides.
 
 #### kotlin
 
@@ -356,7 +331,7 @@ overrides:
     rename:
       id: "Identifier"
     overrides:
-      - db_type: "timestamptz"
+      - db_type: "pg_catalog.timestamptz"
         nullable: true
         engine: "postgresql"
         go_type:
@@ -368,7 +343,7 @@ sql:
   queries: "postgresql/query.sql"
   engine: "postgresql"
   gen:
-    go: 
+    go:
       package: "authors"
       out: "postgresql"
 - schema: "mysql/schema.sql"
@@ -443,6 +418,8 @@ Each mapping in the `packages` collection has the following keys:
   - Either `postgresql` or `mysql`. Defaults to `postgresql`.
 - `sql_package`:
   - Either `pgx/v4`, `pgx/v5` or `database/sql`. Defaults to `database/sql`.
+- `overrides`:
+  - A list of type override configurations. See the [Overriding types](../howto/overrides.md) guide for details.
 - `emit_db_tags`:
   - If true, add DB tags to generated structs. Defaults to `false`.
 - `emit_prepared_queries`:
@@ -494,78 +471,7 @@ Each mapping in the `packages` collection has the following keys:
 
 ### overrides
 
-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`
-instead.
-
-```yaml
-version: "1"
-packages: [...]
-overrides:
-  - go_type: "github.com/gofrs/uuid.UUID"
-    db_type: "uuid"
-```
-
-Each override document 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.
-- `go_type`:
-  - A fully qualified name to a Go type to use in the generated code.
-- `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.
-- `nullable`:
-  - If true, use this type when a column is nullable. 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.
-
-For more complicated import paths, the `go_type` can also be an object.
-
-```yaml
-version: "1"
-packages: [...]
-overrides:
-  - db_type: "uuid"
-    go_type:
-      import: "a/b/v2"
-      package: "b"
-      type: "MyType"
-```
-
-#### Per-Column Type Overrides
-
-Sometimes you would like to override the Go type used in model or query generation for
-a specific field of a table and not on a type basis as described in the previous section.
-
-This may be configured by specifying the `column` property in the override definition. `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`.
-
-```yaml
-version: "1"
-packages: [...]
-overrides:
-  - column: "authors.id"
-    go_type: "github.com/segmentio/ksuid.KSUID"
-```
-
-#### Package Level Overrides
-
-Overrides can be configured globally, as demonstrated in the previous sections, or they can be configured per-package which
-scopes the override behavior to just a single package:
-
-```yaml
-version: "1"
-packages:
-  - overrides: [...]
-```
+See the version 1 configuration section of the [Overriding types](../howto/overrides.md#version-1-configuration) guide for details.
 
 ### rename
 

docs/reference/datatypes.md

@@ -4,7 +4,7 @@
 database types to Go types. Choices for more complex types are described below.
 
 If you're unsatisfied with the default, you can override any type using the
-[overrides list](config.md#type-overriding) in your `sqlc` config file.
+[overrides list](config.md#overrides) in your `sqlc` config file.
 
 ## Arrays
 
@@ -143,7 +143,9 @@ type Author struct {
 }
 ```
 
-For MySQL, there is no native `uuid` data type. When using `UUID_TO_BIN` to store a `UUID()`, the underlying field type is `BINARY(16)` which by default sqlc would interpret this to `sql.NullString`. To have sqlc automatically convert these fields to a `uuid.UUID` type, use an overide on the column storing the `uuid`.
+For MySQL, there is no native `uuid` data type. When using `UUID_TO_BIN` to store a `UUID()`, the underlying field type is `BINARY(16)` which by default sqlc would map to `sql.NullString`. To have sqlc automatically convert these fields to a `uuid.UUID` type, use an overide on the column storing the `uuid`
+(see [Overriding types](../howto/overrides.md) for details).
+
 ```json
 {
   "overrides": [
@@ -158,7 +160,8 @@ For MySQL, there is no native `uuid` data type. When using `UUID_TO_BIN` to stor
 ## JSON
 
 By default, sqlc will generate the `[]byte`, `pgtype.JSON` or `json.RawMessage` for JSON column type.
-But if you use the `pgx/v5` sql package then you can specify a struct instead of default type.
+But if you use the `pgx/v5` sql package then you can specify a struct instead of the default type
+(see [Overriding types](../howto/overrides.md) for details).
 The `pgx` implementation will marshal/unmarshal the struct automatically.
 
 ```go
@@ -209,7 +212,7 @@ type Book struct {
 
 In PostgreSQL, when you have a column with the TEXT type, sqlc will map it to a Go string by default. This default mapping applies to `TEXT` columns that are not nullable. However, for nullable `TEXT` columns, sqlc maps them to `pgtype.Text` when using the pgx/v5 driver. This distinction is crucial for developers looking to handle null values appropriately in their Go applications.
 
-To accommodate nullable strings and map them to `*string` in Go, you can use the `emit_pointers_for_null_types` option in your sqlc configuration. This option ensures that nullable SQL columns are represented as pointer types in Go, allowing for a clear distinction between null and non-null values. Another way to do this is by passing the option `pointer: true` when you are overriding the `TEXT` datatype in you sqlc config file.
+To accommodate nullable strings and map them to `*string` in Go, you can use the `emit_pointers_for_null_types` option in your sqlc configuration. This option ensures that nullable SQL columns are represented as pointer types in Go, allowing for a clear distinction between null and non-null values. Another way to do this is by passing the option `pointer: true` when you are overriding the `TEXT` datatype in your sqlc config file (see [Overriding types](../howto/overrides.md) for details).
 
 ## Geometry
 
@@ -222,7 +225,7 @@ package for working with PostGIS geometry types in [GEOS](https://libgeos.org/).
 
 There are three steps:
 
-1. Configure sqlc to use `*github.com/twpayne/go-geos.Geom` for geometry types.
+1. Configure sqlc to use `*github.com/twpayne/go-geos.Geom` for geometry types (see [Overriding types](../howto/overrides.md) for details).
 2. Call `github.com/twpayne/pgx-geos.Register` on each
    `*github.com/jackc/pgx/v5.Conn`.
 3. Annotate your SQL with `::geometry` typecasts, if needed.
@@ -281,7 +284,7 @@ config.AfterConnect = func(ctx context.Context, conn *pgx.Conn) error {
 #### Using `github.com/twpayne/go-geom`
 
 sqlc can be configured to use the [geom](https://github.com/twpayne/go-geom)
-package for working with PostGIS geometry types.
+package for working with PostGIS geometry types. See [Overriding types](../howto/overrides.md) for more information.
 
 ```sql
 -- Multipolygons in British National Grid (epsg:27700)