Skip to content

Commit a1865ad

Browse files
committed
docs: Add documentation for the upload subcommand
1 parent b1311d6 commit a1865ad

File tree

5 files changed

+68
-5
lines changed

5 files changed

+68
-5
lines changed

docs/guides/privacy.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ We provide a few hosted services in addition to the sqlc command line tool.
4949
* Playground data stored in [Google Cloud Storage](https://cloud.google.com/storage)
5050
* Automatically deleted after 30 days
5151

52-
### api.sqlc.dev
52+
### app.sqlc.dev / api.sqlc.dev
5353

5454
* Hosted on [Heroku](https://heroku.com)
5555
* Error tracking and tracing with [Sentry](https://sentry.io)

docs/howto/upload.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Uploading projects
2+
3+
*This feature requires signing up for [sqlc Cloud](https://app.sqlc.dev), which is currently in beta.*
4+
5+
Uploading your project ensures that future releases of sqlc do not break your
6+
existing code. Similar to Rust's [crater](https://github.com/rust-lang/crater)
7+
project, uploaded projects are tested against development releases of sqlc to
8+
verify correctness.
9+
10+
## Add configuration
11+
12+
After creating a project, add the project ID to your sqlc configuration file.
13+
14+
```yaml
15+
version: "1"
16+
project:
17+
id: "<PROJECT-ID>"
18+
packages: []
19+
```
20+
21+
```json
22+
{
23+
"version": "1",
24+
"project": {
25+
"id": "<PROJECT-ID>"
26+
},
27+
"packages": [
28+
]
29+
}
30+
```
31+
32+
You'll also need to create an API token and make it available via the
33+
`SQLC_AUTH_TOKEN` environment variable.
34+
35+
```shell
36+
export SQLC_AUTH_TOKEN=sqlc_xxxxxxxx
37+
```
38+
39+
## Dry run
40+
41+
You can see what's included when uploading your project by using using the `--dry-run` flag:
42+
43+
```shell
44+
sqlc upload --dry-run
45+
```
46+
47+
The output will be the exact HTTP request sent by `sqlc`.
48+
49+
## Upload
50+
51+
Once you're ready to upload, remove the `--dry-run` flag.
52+
53+
```shell
54+
sqlc upload
55+
```
56+
57+
By uploading your project, you're making sqlc more stable and reliable. Thanks!

docs/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ code ever again.
5353
howto/ddl.md
5454
howto/structs.md
5555

56+
howto/upload.md
57+
5658
.. toctree::
5759
:maxdepth: 2
5860
:caption: Reference

docs/reference/cli.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,17 @@ Usage:
66
77
Available Commands:
88
compile Statically check SQL for syntax and type errors
9+
completion Generate the autocompletion script for the specified shell
910
generate Generate Go code from SQL
1011
help Help about any command
1112
init Create an empty sqlc.yaml settings file
13+
upload Upload the schema, queries, and configuration for this project
1214
version Print the sqlc version number
1315
1416
Flags:
15-
-h, --help help for sqlc
17+
-x, --experimental enable experimental features (default: false)
18+
-f, --file string specify an alternate config file (default: sqlc.yaml)
19+
-h, --help help for sqlc
1620
1721
Use "sqlc [command] --help" for more information about a command.
1822
```

internal/bundler/upload.go

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,6 @@ func (up *Uploader) Validate() error {
4040
}
4141

4242
func (up *Uploader) buildRequest(ctx context.Context, result map[string]string) (*http.Request, error) {
43-
if err := up.Validate(); err != nil {
44-
return nil, err
45-
}
4643
body := bytes.NewBuffer([]byte{})
4744

4845
w := multipart.NewWriter(body)
@@ -80,6 +77,9 @@ func (up *Uploader) DumpRequestOut(ctx context.Context, result map[string]string
8077
}
8178

8279
func (up *Uploader) Upload(ctx context.Context, result map[string]string) error {
80+
if err := up.Validate(); err != nil {
81+
return nil, err
82+
}
8383
req, err := up.buildRequest(ctx, result)
8484
if err != nil {
8585
return err

0 commit comments

Comments
 (0)