sqlc-dev · kyleconroy · Feb 6, 2021 · Feb 6, 2021
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/guides/development.md b/docs/guides/development.md
@@ -0,0 +1,67 @@
+# Developing sqlc
+
+## Building
+
+For local development, install `sqlc` under an alias. We suggest `sqlc-dev`.
+
+```
+go build -o ~/go/bin/sqlc-dev ./cmd/sqlc
+```
+
+## Running Tests
+
+```
+go test ./...
+```
+
+To run the tests in the examples folder, use the `examples` tag.
+
+```
+go test --tags=examples ./...
+```
+
+These tests require locally-running database instances. Run these databases
+using [Docker Compose](https://docs.docker.com/compose/).
+
+```
+docker-compose up -d
+```
+
+The tests use the following environment variables to connect to the
+database
+
+### For PostgreSQL
+
+```
+Variable     Default Value
+-------------------------
+PG_HOST      127.0.0.1
+PG_PORT      5432
+PG_USER      postgres
+PG_PASSWORD  mysecretpassword
+PG_DATABASE  dinotest
+```
+
+### For MySQL
+
+```
+Variable     Default Value
+-------------------------
+MYSQL_HOST      127.0.0.1
+MYSQL_PORT      3306
+MYSQL_USER      root
+MYSQL_ROOT_PASSWORD  mysecretpassword
+MYSQL_DATABASE  dinotest
+```
+
+## Regenerate expected test output
+
+If you need to update a large number of expected test output in the
+`internal/endtoend/testdata` directory, run the `regenerate.sh` script.
+
+```
+make regen
+```
+
+Note that this uses the `sqlc-dev` binary, not `sqlc` so make sure you have an
+up to date `sqlc-dev` binary.
diff --git a/docs/privacy.md → docs/guides/privacy.md b/docs/privacy.md → docs/guides/privacy.md
diff --git a/docs/alter_table.md → docs/howto/alter_table.md b/docs/alter_table.md → docs/howto/alter_table.md
diff --git a/docs/annotations.md → docs/howto/annotations.md b/docs/annotations.md → docs/howto/annotations.md
diff --git a/docs/any.md → docs/howto/any.md b/docs/any.md → docs/howto/any.md
diff --git a/docs/arrays.md → docs/howto/arrays.md b/docs/arrays.md → docs/howto/arrays.md
diff --git a/docs/delete.md → docs/howto/delete.md b/docs/delete.md → docs/howto/delete.md
diff --git a/docs/enums.md → docs/howto/enums.md b/docs/enums.md → docs/howto/enums.md
diff --git a/docs/insert.md → docs/howto/insert.md b/docs/insert.md → docs/howto/insert.md
diff --git a/docs/json_tags.md → docs/howto/json_tags.md b/docs/json_tags.md → docs/howto/json_tags.md
diff --git a/docs/migrations.md → docs/howto/migrations.md b/docs/migrations.md → docs/howto/migrations.md
diff --git a/docs/named_parameters.md → docs/howto/named_parameters.md b/docs/named_parameters.md → docs/howto/named_parameters.md
diff --git a/docs/null.md → docs/howto/null.md b/docs/null.md → docs/howto/null.md
diff --git a/docs/prepared_query.md → docs/howto/prepared_query.md b/docs/prepared_query.md → docs/howto/prepared_query.md
diff --git a/docs/query_count.md → docs/howto/query_count.md b/docs/query_count.md → docs/howto/query_count.md
diff --git a/docs/query_one.md → docs/howto/query_one.md b/docs/query_one.md → docs/howto/query_one.md
diff --git a/docs/returning.md → docs/howto/returning.md b/docs/returning.md → docs/howto/returning.md
diff --git a/docs/table.md → docs/howto/table.md b/docs/table.md → docs/howto/table.md
diff --git a/docs/time.md → docs/howto/time.md b/docs/time.md → docs/howto/time.md
diff --git a/docs/transactions.md → docs/howto/transactions.md b/docs/transactions.md → docs/howto/transactions.md
diff --git a/docs/update.md → docs/howto/update.md b/docs/update.md → docs/howto/update.md
diff --git a/docs/uuid.md → docs/howto/uuid.md b/docs/uuid.md → docs/howto/uuid.md
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,32 +3,76 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to sqlc's documentation!
-================================
+sqlc Documentation
+==================
+
+  And lo, the Great One looked down upon the people and proclaimed:
+    "SQL is actually pretty great"
+
+sqlc generates **fully type-safe idiomatic Go code** from SQL. Here's how it
+works:
+
+1. You write SQL queries
+2. You run sqlc to generate Go code that presents type-safe interfaces to those
+   queries
+3. You write application code that calls the methods sqlc generated
+
+Seriously, it's that easy. You don't have to write any boilerplate SQL querying
+code ever again.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-   README.md
-   alter_table.md
-   annotations.md
-   any.md
-   arrays.md
-   delete.md
-   enums.md
-   insert.md
-   json_tags.md
-   migrations.md
-   named_parameters.md
-   null.md
-   prepared_query.md
-   privacy.md
-   query_count.md
-   query_one.md
-   returning.md
-   table.md
-   time.md
-   transactions.md
-   update.md
-   uuid.md
+   :caption: Overview:
+   :hidden:
+
+   overview/install.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials:
+   :hidden:
+
+   tutorials/getting-started.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: How-to Guides:
+   :hidden:
+
+   howto/alter_table.md
+   howto/annotations.md
+   howto/any.md
+   howto/arrays.md
+   howto/delete.md
+   howto/enums.md
+   howto/insert.md
+   howto/json_tags.md
+   howto/migrations.md
+   howto/named_parameters.md
+   howto/null.md
+   howto/prepared_query.md
+   howto/privacy.md
+   howto/query_count.md
+   howto/query_one.md
+   howto/returning.md
+   howto/table.md
+   howto/time.md
+   howto/transactions.md
+   howto/update.md
+   howto/uuid.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference:
+   :hidden:
+
+   reference/cli.md
+   reference/config.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Conceptual Guides:
+   :hidden:
+
+   guides/development.md
+   guides/privacy.md
diff --git a/docs/overview/install.md b/docs/overview/install.md
@@ -0,0 +1,45 @@
+# Installing sqlc
+
+sqlc is distributed as a single binary with zero dependencies.
+
+## macOS
+
+```
+brew install sqlc
+```
+
+## Ubuntu
+
+```
+sudo snap install sqlc
+```
+
+## go get
+
+```
+go get github.com/kyleconroy/sqlc/cmd/sqlc
+```
+
+## Docker
+
+```
+docker pull kjconroy/sqlc
+```
+
+Run `sqlc` using `docker run`:
+
+```
+docker run --rm -v $(pwd):/src -w /src kjconroy/sqlc generate
+```
+
+## Downloads
+
+Binaries for a given release can be downloaded from the [stable channel on
+Equinox](https://dl.equinox.io/sqlc/sqlc/stable) or the latest [GitHub
+release](https://github.com/kyleconroy/sqlc/releases).
+
+## Tip Releases
+
+Each commit is deployed to the [`devel` channel on Equinox](https://dl.equinox.io/sqlc/sqlc/devel):
+- [Linux](https://bin.equinox.io/c/gvM95th6ps1/sqlc-devel-linux-amd64.tgz)
+- [macOS](https://bin.equinox.io/c/gvM95th6ps1/sqlc-devel-darwin-amd64.zip)
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -0,0 +1,18 @@
+# CLI
+
+```
+Usage:
+  sqlc [command]
+
+Available Commands:
+  compile     Statically check SQL for syntax and type errors
+  generate    Generate Go code from SQL
+  help        Help about any command
+  init        Create an empty sqlc.yaml settings file
+  version     Print the sqlc version number
+
+Flags:
+  -h, --help   help for sqlc
+
+Use "sqlc [command] --help" for more information about a command.
+```
diff --git a/docs/reference/config.md b/docs/reference/config.md
@@ -0,0 +1,122 @@
+# Configuration File (Version 1)
+
+The `sqlc` tool is configured via a `sqlc.yaml` or `sqlc.json` file. This file must be
+in the directory where the `sqlc` command is run.
+
+```yaml
+version: "1"
+packages:
+  - name: "db"
+    path: "internal/db"
+    queries: "./sql/query/"
+    schema: "./sql/schema/"
+    engine: "postgresql"
+    emit_json_tags: true
+    emit_prepared_queries: true
+    emit_interface: false
+    emit_exact_table_names: false
+    emit_empty_slices: false
+```
+
+Each package document has the following keys:
+- `name`:
+  - The package name to use for the generated code. Defaults to `path` basename
+- `path`:
+  - Output directory for generated code
+- `queries`:
+  - Directory of SQL queries or path to single SQL file; or a list of paths
+- `schema`:
+  - Directory of SQL migrations or path to single SQL file; or a list of paths
+- `engine`:
+  - Either `postgresql` or `mysql`. Defaults to `postgresql`. MySQL support is experimental
+- `emit_json_tags`:
+  - If true, add JSON tags to generated structs. Defaults to `false`.
+- `emit_db_tags`:
+  - If true, add DB tags to generated structs. Defaults to `false`.
+- `emit_prepared_queries`:
+  - If true, include support for prepared queries. Defaults to `false`.
+- `emit_interface`:
+  - If true, output a `Querier` interface in the generated package. Defaults to `false`.
+- `emit_exact_table_names`:
+  - If true, struct names will mirror table names. Otherwise, sqlc attempts to singularize plural table names. Defaults to `false`.
+- `emit_empty_slices`:
+  - If true, slices returned by `:many` queries will be empty instead of `nil`. Defaults to `false`.
+
+## Type Overrides
+
+The default mapping of PostgreSQL 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: "1"
+packages: [...]
+overrides:
+  - go_type: "github.com/gofrs/uuid.UUID"
+    db_type: "uuid"
+```
+
+Each override document has the following keys:
+- `db_type`:
+  - The PostgreSQL type to override. Find the full list of supported types in [postgresql_type.go](https://github.com/kyleconroy/sqlc/blob/master/internal/codegen/golang/postgresql_type.go#L12).
+- `go_type`:
+  - A fully qualified name to a Go type to use in the generated code.
+- `nullable`:
+  - If true, use this type when a column is nullable. Defaults to `false`.
+
+## Per-Column Type Overrides
+
+Sometimes you would like to override the Go type used in model or query generation for
+a specific field of a table and not on a type basis as described in the previous section.
+
+This may be configured by specifying the `column` property in the override definition. `column`
+should be of the form `table.column` buy you may be even more specify by specifying `schema.table.column`
+or `catalog.schema.table.column`.
+
+```yaml
+version: "1"
+packages: [...]
+overrides:
+  - column: "authors.id"
+    go_type: "github.com/segmentio/ksuid.KSUID"
+```
+
+## Package Level Overrides
+
+Overrides can be configured globally, as demonstrated in the previous sections, or they can be configured on a per-package which
+scopes the override behavior to just a single package:
+
+```yaml
+version: "1"
+packages:
+  - overrides: [...]
+```
+
+## Renaming Struct 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` dictionary
+to pick a new name. The keys are column names and the values are the struct
+field name to use.
+
+```yaml
+version: "1"
+packages: [...]
+rename:
+  spotify_url: "SpotifyURL"
+```
+
+