From 235fe5c8b7d9c6bb004a4185ee5834dd06adf870 Mon Sep 17 00:00:00 2001
From: Matthew Sanabria <24284972+sudomateo@users.noreply.github.com>
Date: Mon, 19 Sep 2022 00:15:09 -0400
Subject: [PATCH 1/2] Documentation improvements

---
 docs/howto/ddl.md                            | 27 ++++++++++----
 docs/reference/config.md                     |  2 +-
 docs/tutorials/getting-started-postgresql.md | 39 ++++++++++++++------
 3 files changed, 49 insertions(+), 19 deletions(-)

diff --git a/docs/howto/ddl.md b/docs/howto/ddl.md
index e2f36788b9..b0b4d2651e 100644
--- a/docs/howto/ddl.md
+++ b/docs/howto/ddl.md
@@ -1,6 +1,7 @@
 # Modifying the database schema
 
-sqlc understands `ALTER TABLE` statements when parsing SQL.
+sqlc parses `CREATE TABLE` and `ALTER TABLE` statements in order to generate
+the necessary code.
 
 ```sql
 CREATE TABLE authors (
@@ -24,8 +25,11 @@ type Writer struct {
 
 ## Handling SQL migrations
 
-sqlc will ignore rollback statements when parsing migration SQL files. The
-following tools are current supported:
+sqlc does not perform database migrations for you. However, sqlc is able to
+differentiate between up and down migrations. sqlc ignores down migrations when
+parsing SQL files.
+
+sqlc supports parsing migrations from the following tools:
 
 - [dbmate](https://github.com/amacneil/dbmate)
 - [golang-migrate](https://github.com/golang-migrate/migrate)
@@ -98,17 +102,26 @@ type Comment struct {
 
 ### golang-migrate
 
-Warning: [golang-migrate specifies](https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md#migration-filename-format) that the version number in the migration file name is to be interpreted numerically. However, sqlc executes the migration files in **lexicographic** order. If you choose to simply enumerate your migration versions, make sure to prepend enough zeros to the version number to avoid any unexpected behavior.
+**Warning:**
+[golang-migrate interprets](https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md#migration-filename-format)
+migration filenames numerically. However, sqlc parses migration files in
+lexicographic order. If you choose to have sqlc enumerate your migration files,
+make sure their numeric ordering matches their lexicographic ordering to avoid
+unexpected behavior. This can be done by prepending enough zeroes to the
+migration filenames.
+
+This doesn't work as intended.
 
-Probably doesn't work as intended:
 ```
 1_initial.up.sql
 ...
 9_foo.up.sql
-# this migration file will be executed BEFORE 9_foo
+# this migration file will be parsed BEFORE 9_foo
 10_bar.up.sql
 ```
-Works as was probably intended:
+
+This worked as intended.
+
 ```
 001_initial.up.sql
 ...
diff --git a/docs/reference/config.md b/docs/reference/config.md
index 9ba8bcd388..c8cbd9f629 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -35,7 +35,7 @@ Each mapping in the `sql` collection has the following keys:
 - `queries`:
   - Directory of SQL queries or path to single SQL file; or a list of paths.
 - `gen`:
-  - A mapping to configure built-in code generators. Supports the following keys:
+  - A mapping to configure built-in code generators. See [gen](#gen) for the supported keys.
 - `strict_function_checks`
   - If true, return an error if a called SQL function does not exist. Defaults to `false`.
   
diff --git a/docs/tutorials/getting-started-postgresql.md b/docs/tutorials/getting-started-postgresql.md
index 873e9ad2cb..ce5a407ae5 100644
--- a/docs/tutorials/getting-started-postgresql.md
+++ b/docs/tutorials/getting-started-postgresql.md
@@ -23,10 +23,21 @@ packages:
     engine: "postgresql"
     schema: "schema.sql"
     queries: "query.sql"
+
+version: "2"
+sql:
+  - engine: "postgresql"
+    queries: "query.sql"
+    schema: "schema.sql"
+    gen:
+      go:
+        package: "tutorial"
+        out: "tutorial"
 ```
 
-sqlc needs to know your database schema and queries. In the same directory,
-create a file named `schema.sql` with the following contents:
+sqlc needs to know your database schema and queries in order to generate code.
+In the same directory, create a file named `schema.sql` with the following
+content:
 
 ```sql
 CREATE TABLE authors (
@@ -60,25 +71,30 @@ DELETE FROM authors
 WHERE id = $1;
 ```
 
-For SQL UPDATE if you do not want to return the updated record to the user, add this to the `query.sql` file:
+If you **do not** want your SQL `UPDATE` queries to return the updated record
+to the user, add this to `query.sql`:
+
 ```sql
 -- name: UpdateAuthor :exec
 UPDATE authors
-set name = $2,
-bio = $3
+  set name = $2,
+  bio = $3
 WHERE id = $1;
 ```
-Otherwise, to return the updated record back to the user, add this to the `query.sql` file:
+
+Otherwise, to return the updated record to the user, add this to the
+`query.sql`:
+
 ```sql
 -- name: UpdateAuthor :one
 UPDATE authors
-set name = $2,
-bio = $3
+  set name = $2,
+  bio = $3
 WHERE id = $1
 RETURNING *;
 ```
 
-You are now ready to generate code. Run the `generate` command. You shouldn't see any errors or output.
+You are now ready to generate code. You shouldn't see any errors or output.
 
 ```shell
 sqlc generate
@@ -165,5 +181,6 @@ go get github.com/lib/pq
 go build ./...
 ```
 
-To make that possible, sqlc generates readable, **idiomatic** Go code that you
-otherwise would have had to write yourself. Take a look in `tutorial/query.sql.go`.
+sqlc generates readable, **idiomatic** Go code that you otherwise would have
+had to write yourself. Take a look in the `tutorial` package to see what code
+sqlc generated.

From 4c1313dc98428d16cd686f45af7c6b81eb4cbde3 Mon Sep 17 00:00:00 2001
From: Matthew Sanabria <24284972+sudomateo@users.noreply.github.com>
Date: Mon, 19 Sep 2022 00:46:46 -0400
Subject: [PATCH 2/2] Implement review feedback

---
 docs/tutorials/getting-started-postgresql.md | 11 +----------
 1 file changed, 1 insertion(+), 10 deletions(-)

diff --git a/docs/tutorials/getting-started-postgresql.md b/docs/tutorials/getting-started-postgresql.md
index ce5a407ae5..4fe2bfd361 100644
--- a/docs/tutorials/getting-started-postgresql.md
+++ b/docs/tutorials/getting-started-postgresql.md
@@ -16,14 +16,6 @@ directory. In our new directory, create a file named `sqlc.yaml` with the
 following contents:
 
 ```yaml
-version: 1
-packages:
-  - path: "tutorial"
-    name: "tutorial"
-    engine: "postgresql"
-    schema: "schema.sql"
-    queries: "query.sql"
-
 version: "2"
 sql:
   - engine: "postgresql"
@@ -82,8 +74,7 @@ UPDATE authors
 WHERE id = $1;
 ```
 
-Otherwise, to return the updated record to the user, add this to the
-`query.sql`:
+Otherwise, to return the updated record to the user, add this to `query.sql`:
 
 ```sql
 -- name: UpdateAuthor :one