docs: Pull renaming and type overrides into separate sections (#2774)

kyleconroy · web-flow · commit f4b15a06eaca · 2023-09-25T18:03:02.000-07:00
diff --git a/docs/howto/overrides.md b/docs/howto/overrides.md
@@ -0,0 +1,79 @@
+# 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`
+instead.
+
+```yaml
+version: "2"
+sql:
+- schema: "postgresql/schema.sql"
+  queries: "postgresql/query.sql"
+  engine: "postgresql"
+  gen:
+    go: 
+      package: "authors"
+      out: "postgresql"
+      overrides:
+        - db_type: "uuid"
+          go_type: "github.com/gofrs/uuid.UUID"
+```
+
+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`.
+
+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.
+
+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.
+
+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.
+
+An example:
+
+```yaml
+version: "2"
+sql:
+- schema: "postgresql/schema.sql"
+  queries: "postgresql/query.sql"
+  engine: "postgresql"
+  gen:
+    go: 
+      package: "authors"
+      out: "postgresql"
+      overrides:
+        - db_type: "uuid"
+          go_type:
+            import: "a/b/v2"
+            package: "b"
+            type: "MyType"
+            pointer: true
+```
diff --git a/docs/howto/rename.md b/docs/howto/rename.md
@@ -0,0 +1,87 @@
+# Renaming fields
+
+Struct field names are generated from column names using a simple algorithm:
+split the column name on underscores and capitalize the first letter of each
+part.
+
+```
+account     -> Account
+spotify_url -> SpotifyUrl
+app_id      -> AppID
+```
+
+If you're not happy with a field's generated name, use the `rename` mapping
+to pick a new name. The keys are column names and the values are the struct
+field name to use.
+
+```yaml
+version: "2"
+sql:
+- schema: "postgresql/schema.sql"
+  queries: "postgresql/query.sql"
+  engine: "postgresql"
+  gen:
+    go: 
+      package: "authors"
+      out: "postgresql"
+      rename:
+        spotify_url: "SpotifyURL"
+```
+
+## Tables
+
+The output structs associated with tables can also be renamed. By default, the struct name will be the singular version of the table name. For example, the `authors` table will generate an `Author` struct.
+
+```sql
+CREATE TABLE authors (
+  id   BIGSERIAL PRIMARY KEY,
+  name text      NOT NULL,
+  bio  text
+);
+```
+
+```go
+package db
+
+import (
+	"database/sql"
+)
+
+type Author struct {
+	ID   int64
+	Name string
+	Bio  sql.NullString
+}
+```
+
+To rename this struct, you must use the generated struct name. In this example, that would be `author`. Use the `rename` map to change the name of this struct to `Writer` (note the uppercase `W`).
+
+```yaml
+version: '1'
+packages:
+- path: db
+  engine: postgresql
+  schema: query.sql
+  queries: query.sql
+rename:
+  author: Writer
+```
+
+```go
+package db
+
+import (
+	"database/sql"
+)
+
+type Writer struct {
+	ID   int64
+	Name string
+	Bio  sql.NullString
+}
+```
+
+## Limitations
+
+Rename mappings apply to an entire package. Therefore, a column named `foo` and
+a table name `foo` can't be renamed different values.
diff --git a/docs/index.rst b/docs/index.rst
@@ -54,6 +54,8 @@ code ever again.
    howto/ddl.md
    howto/structs.md
    howto/embedding.md
+   howto/overrides.md
+   howto/rename.md
 
    howto/vet.md
    howto/managed-databases.md
diff --git a/docs/reference/config.md b/docs/reference/config.md
@@ -167,66 +167,13 @@ The `gen` mapping supports the following keys:
 - `query_parameter_limit`:
   - The number of positional arguments that will be generated for Go functions. To always emit a parameter struct, set this to `0`. Defaults to `1`.
 - `rename`:
-  - Customize the name of generated struct fields. Explained in detail on the `Renaming fields` section.
+  - 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. Explained in detail on the  `Type overriding` section.
+  - It is a collection of definitions that dictates which types are used to map a database types.
 
-##### Renaming fields
+##### `overrides`
 
-Struct field names are generated from column names using a simple algorithm:
-split the column name on underscores and capitalize the first letter of each
-part.
-
-```
-account     -> Account
-spotify_url -> SpotifyUrl
-app_id      -> AppID
-```
-
-If you're not happy with a field's generated name, use the `rename` mapping
-to pick a new name. The keys are column names and the values are the struct
-field name to use.
-
-```yaml
-version: "2"
-sql:
-- schema: "postgresql/schema.sql"
-  queries: "postgresql/query.sql"
-  engine: "postgresql"
-  gen:
-    go: 
-      package: "authors"
-      out: "postgresql"
-      rename:
-        spotify_url: "SpotifyURL"
-```
-
-##### Type overriding
-
-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: "2"
-sql:
-- schema: "postgresql/schema.sql"
-  queries: "postgresql/query.sql"
-  engine: "postgresql"
-  gen:
-    go: 
-      package: "authors"
-      out: "postgresql"
-      overrides:
-        - db_type: "uuid"
-          go_type: "github.com/gofrs/uuid.UUID"
-```
-
-Each mapping of the `overrides` collection has the following keys:
+See [Overriding types](../howto/overrides.md) for 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.
@@ -240,13 +187,6 @@ Each mapping of the `overrides` collection has the following keys:
 - `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.
-
-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.
-
 For more complicated import paths, the `go_type` can also be an object with the following keys:
 
 - `import`:
@@ -260,27 +200,6 @@ For more complicated import paths, the `go_type` can also be an object with the
 - `slice`:
   - If set to `true`, generated code will use a slice of the type rather than the type itself.
 
-An example:
-
-```yaml
-version: "2"
-sql:
-- schema: "postgresql/schema.sql"
-  queries: "postgresql/query.sql"
-  engine: "postgresql"
-  gen:
-    go: 
-      package: "authors"
-      out: "postgresql"
-      overrides:
-        - db_type: "uuid"
-          go_type:
-            import: "a/b/v2"
-            package: "b"
-            type: "MyType"
-            pointer: true
-```
-
 #### kotlin
 
 > Removed in v1.17.0 and replaced by the [sqlc-gen-kotlin](https://github.com/sqlc-dev/sqlc-gen-kotlin) plugin. Follow the [migration guide](../guides/migrating-to-sqlc-gen-kotlin) to switch.
diff --git a/docs/reference/datatypes.md b/docs/reference/datatypes.md
@@ -199,3 +199,47 @@ type Book struct {
     Data *dto.BookData
 }
 ```
+
+## Geometry
+
+### PostGIS
+
+sqlc can be configured to use the [geom](https://github.com/twpayne/go-geom)
+package for working with PostGIS geometry types.
+
+```sql
+-- Multipolygons in British National Grid (epsg:27700)
+create table shapes(
+  id serial,
+  name varchar,
+  geom geometry(Multipolygon, 27700)
+);
+
+-- name: GetShapes :many
+SELECT * FROM shapes;
+```
+
+```json
+{
+  "version": "1",
+  "packages": [
+    {
+      "path": "db",
+      "engine": "postgresql",
+      "schema": "query.sql",
+      "queries": "query.sql"
+    }
+  ],
+  "overrides": [
+    {
+      "db_type": "geometry",
+      "go_type": "github.com/twpayne/go-geom.MultiPolygon"
+  	},
+  	{
+      "db_type": "geometry",
+  	  "go_type": "github.com/twpayne/go-geom.MultiPolygon",
+  	  "null": true
+  	}
+  ]
+}
+```
