From c4678ec866e47921a375baba24dfa9203a825e1b Mon Sep 17 00:00:00 2001 From: Kyle Conroy Date: Mon, 25 Sep 2023 17:26:37 -0700 Subject: [PATCH] docs: Pull renaming and type overrides into separate sections --- docs/howto/overrides.md | 79 ++++++++++++++++++++++++++++++++ docs/howto/rename.md | 87 ++++++++++++++++++++++++++++++++++++ docs/index.rst | 2 + docs/reference/config.md | 89 ++----------------------------------- docs/reference/datatypes.md | 44 ++++++++++++++++++ 5 files changed, 216 insertions(+), 85 deletions(-) create mode 100644 docs/howto/overrides.md create mode 100644 docs/howto/rename.md diff --git a/docs/howto/overrides.md b/docs/howto/overrides.md new file mode 100644 index 0000000000..baa9163c4d --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/howto/rename.md b/docs/howto/rename.md new file mode 100644 index 0000000000..f2d03e6cba --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index f9ddc47b29..566d87d84f 100644 --- 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 index 1ce09b4038..3aabc90ca1 100644 --- 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 index b7cf5f6ef7..4dee0fae92 100644 --- 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 + } + ] +} +``` \ No newline at end of file