Skip to content

Commit 05c1d25

Browse files
kyleconroykyleconroy
authored
Add docs for Kotlin / Python migration (#1929)
* docs: Add first pass at Python / Kotlin migratitions * Finish Kotlin guide * docs: Update Python plugin URLs to placeholders
1 parent 087abf9 commit 05c1d25

2 files changed

Lines changed: 250 additions & 0 deletions

File tree

‎docs/guides/migrating-to-sqlc-gen-kotlin.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Migrating to sqlc-gen-kotlin
2+
3+
Starting in sqlc 1.16.0, built-in Kotlin support has been deprecated. It will
4+
be fully removed in 1.17.0 in favor of sqlc-gen-kotlin.
5+
6+
This guide will walk you through migrating to the [sqlc-gen-kotlin] plugin,
7+
which involves three steps.
8+
9+
1. Add the sqlc-gen-kotlin plugin
10+
2. Migrate each package
11+
3. Re-generate the code
12+
13+
## Add the sqlc-gen-kotlin plugin
14+
15+
In your configuration file, add a `plugins` array if you don't have one
16+
already. Add the following configuration for the plugin:
17+
18+
```json
19+
{
20+
"version": "2",
21+
"plugins": [
22+
{
23+
"name": "kt",
24+
"wasm": {
25+
"url": "https://downloads.sqlc.dev/plugins/sqlc-gen-kotlin_0.16.0.wasm",
26+
"sha256": "FIXME"
27+
}
28+
}
29+
]
30+
}
31+
```
32+
33+
```yaml
34+
version: "2"
35+
plugins:
36+
name: "kt"
37+
wasm:
38+
url: "https://downloads.sqlc.dev/plugins/sqlc-gen-kotlin_0.16.0.wasm"
39+
sha256: "FIXME"
40+
```
41+
42+
## Migrate each package
43+
44+
Your package configuration should currently looks something like this for JSON.
45+
46+
```json
47+
"sql": [
48+
{
49+
"schema": "schema.sql",
50+
"queries": "query.sql",
51+
"engine": "postgresql",
52+
"gen": {
53+
"kotlin": {
54+
"out": "src/main/kotlin/com/example/foo",
55+
"package": "com.example.foo"
56+
}
57+
}
58+
}
59+
]
60+
```
61+
62+
Or this if you're using YAML.
63+
64+
```yaml
65+
sql:
66+
- schema: "schema.sql"
67+
queries: "query.sql"
68+
engine: "postgresql"
69+
gen:
70+
kotlin:
71+
out: "src/main/kotlin/com/example/foo"
72+
package: "com.example.foo"
73+
```
74+
75+
To use the plugin, you'll need to replace the `gen` mapping with the `codegen`
76+
collection. Add the `plugin` field, setting it to `kt`. All fields other than
77+
`out` need to be moved into the `options` mapping.
78+
79+
After you're done, it should look like this for JSON.
80+
81+
```json
82+
"sql": [
83+
{
84+
"schema": "schema.sql",
85+
"queries": "query.sql",
86+
"engine": "postgresql",
87+
"codegen": [
88+
{
89+
"out": "src/main/kotlin/com/example/foo",
90+
"plugin": "kt",
91+
"options": {
92+
"package": "com.example.foo"
93+
}
94+
}
95+
]
96+
}
97+
]
98+
```
99+
100+
Or this for YAML.
101+
102+
```yaml
103+
sql:
104+
- schema: "schema.sql"
105+
queries: "query.sql"
106+
engine: "postgresql"
107+
codegen:
108+
- plugin: "kt"
109+
out: "src/main/kotlin/com/example/foo"
110+
options:
111+
package: "com.example.foo"
112+
```
113+
114+
## Re-generate the code
115+
116+
Run `sqlc generate`. The plugin will produce the same output, so you shouldn't
117+
see any changes. The first time `sqlc generate` is run, the plugin must be
118+
downloaded and compiled, resulting in a slightly longer runtime. Subsequent
119+
`generate` calls will be fast.

‎docs/guides/migrating-to-sqlc-gen-python.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Migrating to sqlc-gen-python
2+
3+
Starting in sqlc 1.16.0, built-in Python support has been deprecated. It will
4+
be fully removed in 1.17.0 in favor of sqlc-gen-python.
5+
6+
This guide will walk you through migrating to the [sqlc-gen-python] plugin,
7+
which involves three steps.
8+
9+
1. Add the sqlc-gen-python plugin
10+
2. Migrate each package
11+
3. Re-generate the code
12+
13+
## Add the sqlc-gen-python plugin
14+
15+
In your configuration file, add a `plugins` array if you don't have one
16+
already. Add the following configuration for the plugin:
17+
18+
```json
19+
{
20+
"version": "2",
21+
"plugins": [
22+
{
23+
"name": "py",
24+
"wasm": {
25+
"url": "https://downloads.sqlc.dev/plugins/sqlc-gen-python_0.16.0.wasm",
26+
"sha256": "FIXME"
27+
}
28+
}
29+
]
30+
}
31+
```
32+
33+
```yaml
34+
version: "2"
35+
plugins:
36+
name: py,
37+
wasm:
38+
url: "https://downloads.sqlc.dev/plugins/sqlc-gen-python_0.16.0.wasm"
39+
sha256: "FIXME"
40+
```
41+
42+
## Migrate each package
43+
44+
Your package configuration should currently looks something like this for JSON.
45+
46+
```json
47+
"sql": [
48+
{
49+
"schema": "schema.sql",
50+
"queries": "query.sql",
51+
"engine": "postgresql",
52+
"gen": {
53+
"python": {
54+
"out": "src",
55+
"package": "foo",
56+
"emit_sync_querier": true,
57+
"emit_async_querier": true,
58+
"query_parameter_limit": 5
59+
}
60+
}
61+
}
62+
]
63+
```
64+
65+
Or this if you're using YAML.
66+
67+
```yaml
68+
sql:
69+
- schema: "schema.sql"
70+
queries: "query.sql"
71+
engine: "postgresql"
72+
gen:
73+
python:
74+
out: "src"
75+
package: "foo"
76+
emit_sync_querier: true
77+
emit_async_querier: true
78+
query_parameter_limit: 5
79+
```
80+
81+
To use the plugin, you'll need to replace the `gen` mapping with the `codegen`
82+
collection. Add the `plugin` field, setting it to `py`. All fields other than
83+
`out` need to be moved into the `options` mapping.
84+
85+
After you're done, it should look like this for JSON.
86+
87+
```json
88+
"sql": [
89+
{
90+
"schema": "schema.sql",
91+
"queries": "query.sql",
92+
"engine": "postgresql",
93+
"codegen": [
94+
{
95+
"out": "src",
96+
"plugin": "py",
97+
"options": {
98+
"package": "authors",
99+
"emit_sync_querier": true,
100+
"emit_async_querier": true,
101+
"query_parameter_limit": 5
102+
}
103+
}
104+
]
105+
}
106+
]
107+
```
108+
109+
Or this for YAML.
110+
111+
```yaml
112+
sql:
113+
- schema: "schema.sql"
114+
queries: "query.sql"
115+
engine: "postgresql"
116+
codegen:
117+
- plugin: "py"
118+
out: "src"
119+
options:
120+
package: "foo"
121+
emit_sync_querier: true
122+
emit_async_querier: true
123+
query_parameter_limit: 5
124+
```
125+
126+
## Re-generate the code
127+
128+
Run `sqlc generate`. The plugin will produce the same output, so you shouldn't
129+
see any changes. The first time `sqlc generate` is run, the plugin must be
130+
downloaded and compiled, resulting in a slightly longer runtime. Subsequent
131+
`generate` calls will be fast.

0 commit comments

Comments
 (0)