docs: Add documentation for the upload subcommand

Author: kyleconroy

docs/guides/privacy.md

@@ -49,7 +49,7 @@ We provide a few hosted services in addition to the sqlc command line tool.
 * Playground data stored in [Google Cloud Storage](https://cloud.google.com/storage)
   * Automatically deleted after 30 days
 
-### api.sqlc.dev
+### app.sqlc.dev / api.sqlc.dev
 
 * Hosted on [Heroku](https://heroku.com)
 * Error tracking and tracing with [Sentry](https://sentry.io)

docs/howto/upload.md

@@ -0,0 +1,57 @@
+# Uploading projects
+
+*This feature requires signing up for [sqlc Cloud](https://app.sqlc.dev), which is currently in beta.*
+
+Uploading your project ensures that future releases of sqlc do not break your
+existing code. Similar to Rust's [crater](https://github.com/rust-lang/crater)
+project, uploaded projects are tested against development releases of sqlc to
+verify correctness.
+
+## Add configuration
+
+After creating a project, add the project ID to your sqlc configuration file.
+
+```yaml
+version: "1"
+project:
+  id: "<PROJECT-ID>"
+packages: []
+```
+
+```json
+{
+  "version": "1",
+  "project": {
+    "id": "<PROJECT-ID>"
+  },
+  "packages": [
+  ]
+}
+```
+
+You'll also need to create an API token and make it available via the
+`SQLC_AUTH_TOKEN` environment variable.
+
+```shell
+export SQLC_AUTH_TOKEN=sqlc_xxxxxxxx
+```
+
+## Dry run
+
+You can see what's included when uploading your project by using using the `--dry-run` flag:
+
+```shell
+sqlc upload --dry-run
+```
+
+The output will be the exact HTTP request sent by `sqlc`.
+
+## Upload
+
+Once you're ready to upload, remove the `--dry-run` flag.
+
+```shell
+sqlc upload
+```
+
+By uploading your project, you're making sqlc more stable and reliable. Thanks!

docs/index.rst

@@ -53,6 +53,8 @@ code ever again.
    howto/ddl.md
    howto/structs.md
 
+   howto/upload.md
+
 .. toctree::
    :maxdepth: 2
    :caption: Reference

docs/reference/cli.md

@@ -6,13 +6,17 @@ Usage:
 
 Available Commands:
   compile     Statically check SQL for syntax and type errors
+  completion  Generate the autocompletion script for the specified shell
   generate    Generate Go code from SQL
   help        Help about any command
   init        Create an empty sqlc.yaml settings file
+  upload      Upload the schema, queries, and configuration for this project
   version     Print the sqlc version number
 
 Flags:
-  -h, --help   help for sqlc
+  -x, --experimental   enable experimental features (default: false)
+  -f, --file string    specify an alternate config file (default: sqlc.yaml)
+  -h, --help           help for sqlc
 
 Use "sqlc [command] --help" for more information about a command.
 ```

internal/bundler/upload.go

@@ -40,9 +40,6 @@ func (up *Uploader) Validate() error {
 }
 
 func (up *Uploader) buildRequest(ctx context.Context, result map[string]string) (*http.Request, error) {
-	if err := up.Validate(); err != nil {
-		return nil, err
-	}
 	body := bytes.NewBuffer([]byte{})
 
 	w := multipart.NewWriter(body)
@@ -80,6 +77,9 @@ func (up *Uploader) DumpRequestOut(ctx context.Context, result map[string]string
 }
 
 func (up *Uploader) Upload(ctx context.Context, result map[string]string) error {
+	if err := up.Validate(); err != nil {
+		return nil, err
+	}
 	req, err := up.buildRequest(ctx, result)
 	if err != nil {
 		return err