Skip to content

Commit f4b15a0

Browse files
kyleconroykyleconroy
authored
docs: Pull renaming and type overrides into separate sections (#2774)
1 parent 00c4f34 commit f4b15a0

File tree

5 files changed

+216
-85
lines changed

5 files changed

+216
-85
lines changed

‎docs/howto/overrides.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Overriding types
2+
3+
The default mapping of PostgreSQL/MySQL types to Go types only uses packages outside
4+
the standard library when it must.
5+
6+
For example, the `uuid` PostgreSQL type is mapped to `github.com/google/uuid`.
7+
If a different Go package for UUIDs is required, specify the package in the
8+
`overrides` array. In this case, I'm going to use the `github.com/gofrs/uuid`
9+
instead.
10+
11+
```yaml
12+
version: "2"
13+
sql:
14+
- schema: "postgresql/schema.sql"
15+
queries: "postgresql/query.sql"
16+
engine: "postgresql"
17+
gen:
18+
go:
19+
package: "authors"
20+
out: "postgresql"
21+
overrides:
22+
- db_type: "uuid"
23+
go_type: "github.com/gofrs/uuid.UUID"
24+
```
25+
26+
Each mapping of the `overrides` collection has the following keys:
27+
28+
- `db_type`:
29+
- 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.
30+
- `column`:
31+
- 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.
32+
- `go_type`:
33+
- A fully qualified name to a Go type to use in the generated code.
34+
- `go_struct_tag`:
35+
- A reflect-style struct tag to use in the generated code, e.g. `a:"b" x:"y,z"`.
36+
If you want general json/db tags for all fields, use `emit_db_tags` and/or `emit_json_tags` instead.
37+
- `nullable`:
38+
- If `true`, use this type when a column is nullable. Defaults to `false`.
39+
40+
Note that a single `db_type` override configuration applies to either nullable or non-nullable
41+
columns, but not both. If you want a single `go_type` to override in both cases, you'll
42+
need to specify two overrides.
43+
44+
When generating code, entries using the `column` key will always have preference over
45+
entries using the `db_type` key in order to generate the struct.
46+
47+
For more complicated import paths, the `go_type` can also be an object with the following keys:
48+
49+
- `import`:
50+
- The import path for the package where the type is defined.
51+
- `package`:
52+
- 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.
53+
- `type`:
54+
- The type name itself, without any package prefix.
55+
- `pointer`:
56+
- If set to `true`, generated code will use pointers to the type rather than the type itself.
57+
- `slice`:
58+
- If set to `true`, generated code will use a slice of the type rather than the type itself.
59+
60+
An example:
61+
62+
```yaml
63+
version: "2"
64+
sql:
65+
- schema: "postgresql/schema.sql"
66+
queries: "postgresql/query.sql"
67+
engine: "postgresql"
68+
gen:
69+
go:
70+
package: "authors"
71+
out: "postgresql"
72+
overrides:
73+
- db_type: "uuid"
74+
go_type:
75+
import: "a/b/v2"
76+
package: "b"
77+
type: "MyType"
78+
pointer: true
79+
```

‎docs/howto/rename.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Renaming fields
2+
3+
Struct field names are generated from column names using a simple algorithm:
4+
split the column name on underscores and capitalize the first letter of each
5+
part.
6+
7+
```
8+
account -> Account
9+
spotify_url -> SpotifyUrl
10+
app_id -> AppID
11+
```
12+
13+
If you're not happy with a field's generated name, use the `rename` mapping
14+
to pick a new name. The keys are column names and the values are the struct
15+
field name to use.
16+
17+
```yaml
18+
version: "2"
19+
sql:
20+
- schema: "postgresql/schema.sql"
21+
queries: "postgresql/query.sql"
22+
engine: "postgresql"
23+
gen:
24+
go:
25+
package: "authors"
26+
out: "postgresql"
27+
rename:
28+
spotify_url: "SpotifyURL"
29+
```
30+
31+
## Tables
32+
33+
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.
34+
35+
```sql
36+
CREATE TABLE authors (
37+
id BIGSERIAL PRIMARY KEY,
38+
name text NOT NULL,
39+
bio text
40+
);
41+
```
42+
43+
```go
44+
package db
45+
46+
import (
47+
"database/sql"
48+
)
49+
50+
type Author struct {
51+
ID int64
52+
Name string
53+
Bio sql.NullString
54+
}
55+
```
56+
57+
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`).
58+
59+
```yaml
60+
version: '1'
61+
packages:
62+
- path: db
63+
engine: postgresql
64+
schema: query.sql
65+
queries: query.sql
66+
rename:
67+
author: Writer
68+
```
69+
70+
```go
71+
package db
72+
73+
import (
74+
"database/sql"
75+
)
76+
77+
type Writer struct {
78+
ID int64
79+
Name string
80+
Bio sql.NullString
81+
}
82+
```
83+
84+
## Limitations
85+
86+
Rename mappings apply to an entire package. Therefore, a column named `foo` and
87+
a table name `foo` can't be renamed different values.

‎docs/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ code ever again.
5454
howto/ddl.md
5555
howto/structs.md
5656
howto/embedding.md
57+
howto/overrides.md
58+
howto/rename.md
5759

5860
howto/vet.md
5961
howto/managed-databases.md

‎docs/reference/config.md

Lines changed: 4 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -167,66 +167,13 @@ The `gen` mapping supports the following keys:
167167
- `query_parameter_limit`:
168168
- 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`.
169169
- `rename`:
170-
- Customize the name of generated struct fields. Explained in detail on the `Renaming fields` section.
170+
- Customize the name of generated struct fields. See [Renaming fields](../howto/rename.md) for usage information.
171171
- `overrides`:
172-
- 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.
172+
- It is a collection of definitions that dictates which types are used to map a database types.
173173

174-
##### Renaming fields
174+
##### `overrides`
175175

176-
Struct field names are generated from column names using a simple algorithm:
177-
split the column name on underscores and capitalize the first letter of each
178-
part.
179-
180-
```
181-
account -> Account
182-
spotify_url -> SpotifyUrl
183-
app_id -> AppID
184-
```
185-
186-
If you're not happy with a field's generated name, use the `rename` mapping
187-
to pick a new name. The keys are column names and the values are the struct
188-
field name to use.
189-
190-
```yaml
191-
version: "2"
192-
sql:
193-
- schema: "postgresql/schema.sql"
194-
queries: "postgresql/query.sql"
195-
engine: "postgresql"
196-
gen:
197-
go:
198-
package: "authors"
199-
out: "postgresql"
200-
rename:
201-
spotify_url: "SpotifyURL"
202-
```
203-
204-
##### Type overriding
205-
206-
The default mapping of PostgreSQL/MySQL types to Go types only uses packages outside
207-
the standard library when it must.
208-
209-
For example, the `uuid` PostgreSQL type is mapped to `github.com/google/uuid`.
210-
If a different Go package for UUIDs is required, specify the package in the
211-
`overrides` array. In this case, I'm going to use the `github.com/gofrs/uuid`
212-
instead.
213-
214-
```yaml
215-
version: "2"
216-
sql:
217-
- schema: "postgresql/schema.sql"
218-
queries: "postgresql/query.sql"
219-
engine: "postgresql"
220-
gen:
221-
go:
222-
package: "authors"
223-
out: "postgresql"
224-
overrides:
225-
- db_type: "uuid"
226-
go_type: "github.com/gofrs/uuid.UUID"
227-
```
228-
229-
Each mapping of the `overrides` collection has the following keys:
176+
See [Overriding types](../howto/overrides.md) for in-depth guide to using type overrides. Each mapping of the `overrides` collection has the following keys:
230177

231178
- `db_type`:
232179
- 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:
240187
- `nullable`:
241188
- If `true`, use this type when a column is nullable. Defaults to `false`.
242189

243-
Note that a single `db_type` override configuration applies to either nullable or non-nullable
244-
columns, but not both. If you want a single `go_type` to override in both cases, you'll
245-
need to specify two overrides.
246-
247-
When generating code, entries using the `column` key will always have preference over
248-
entries using the `db_type` key in order to generate the struct.
249-
250190
For more complicated import paths, the `go_type` can also be an object with the following keys:
251191

252192
- `import`:
@@ -260,27 +200,6 @@ For more complicated import paths, the `go_type` can also be an object with the
260200
- `slice`:
261201
- If set to `true`, generated code will use a slice of the type rather than the type itself.
262202

263-
An example:
264-
265-
```yaml
266-
version: "2"
267-
sql:
268-
- schema: "postgresql/schema.sql"
269-
queries: "postgresql/query.sql"
270-
engine: "postgresql"
271-
gen:
272-
go:
273-
package: "authors"
274-
out: "postgresql"
275-
overrides:
276-
- db_type: "uuid"
277-
go_type:
278-
import: "a/b/v2"
279-
package: "b"
280-
type: "MyType"
281-
pointer: true
282-
```
283-
284203
#### kotlin
285204

286205
> 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.

‎docs/reference/datatypes.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,3 +199,47 @@ type Book struct {
199199
Data *dto.BookData
200200
}
201201
```
202+
203+
## Geometry
204+
205+
### PostGIS
206+
207+
sqlc can be configured to use the [geom](https://github.com/twpayne/go-geom)
208+
package for working with PostGIS geometry types.
209+
210+
```sql
211+
-- Multipolygons in British National Grid (epsg:27700)
212+
create table shapes(
213+
id serial,
214+
name varchar,
215+
geom geometry(Multipolygon, 27700)
216+
);
217+
218+
-- name: GetShapes :many
219+
SELECT * FROM shapes;
220+
```
221+
222+
```json
223+
{
224+
"version": "1",
225+
"packages": [
226+
{
227+
"path": "db",
228+
"engine": "postgresql",
229+
"schema": "query.sql",
230+
"queries": "query.sql"
231+
}
232+
],
233+
"overrides": [
234+
{
235+
"db_type": "geometry",
236+
"go_type": "github.com/twpayne/go-geom.MultiPolygon"
237+
},
238+
{
239+
"db_type": "geometry",
240+
"go_type": "github.com/twpayne/go-geom.MultiPolygon",
241+
"null": true
242+
}
243+
]
244+
}
245+
```

0 commit comments

Comments
 (0)