Reorganzie and conslidate the existing documentation (#885)

* docs: Reorganize and consolidate documentation

Author: kyleconroy

docs/guides/privacy.md

@@ -1,4 +1,4 @@
-# Privacy and Data Collection
+# Privacy and data collection
 
 These days, it feels like every piece of software is tracking you. From your
 browser, to your phone, to your terminal, programs collect as much data about

docs/howto/alter_table.md

@@ -1,14 +1,39 @@
-# Migrations
+# Modifying the database schema
 
-sqlc will ignore rollback statements when parsing migration SQL files. The following tools are current supported:
+sqlc understands `ALTER TABLE` statements when parsing SQL.
 
+```sql
+CREATE TABLE authors (
+  id          SERIAL PRIMARY KEY,
+  birth_year  int    NOT NULL
+);
+
+ALTER TABLE authors ADD COLUMN bio text NOT NULL;
+ALTER TABLE authors DROP COLUMN birth_year;
+ALTER TABLE authors RENAME TO writers;
+```
+
+```go
+package db
+
+type Writer struct {
+	ID  int
+	Bio string
+}
+```
+
+## Handling SQL migrations
+
+sqlc will ignore rollback statements when parsing migration SQL files. The
+following tools are current supported:
+
+- [dbmate](https://github.com/amacneil/dbmate)
+- [golang-migrate](https://github.com/golang-migrate/migrate)
 - [goose](https://github.com/pressly/goose)
 - [sql-migrate](https://github.com/rubenv/sql-migrate)
 - [tern](https://github.com/jackc/tern)
-- [golang-migrate](https://github.com/golang-migrate/migrate)
-- [dbmate](https://github.com/amacneil/dbmate)
 
-## goose
+### goose
 
 ```sql
 -- +goose Up
@@ -71,7 +96,7 @@ type Comment struct {
 }
 ```
 
-## golang-migrate
+### golang-migrate
 
 In `20060102.up.sql`:
 
@@ -100,7 +125,7 @@ type Post struct {
 }
 ```
 
-## dbmate
+### dbmate
 
 ```sql
 -- migrate:up

docs/howto/any.md

@@ -1,4 +1,4 @@
-# Deleting records
+# Deleting rows
 
 ```sql
 CREATE TABLE authors (

docs/howto/arrays.md

@@ -1,4 +1,4 @@
-# Inserting records
+# Inserting rows
 
 ```sql
 CREATE TABLE authors (
@@ -39,3 +39,100 @@ func (q *Queries) CreateAuthor(ctx context.Context, bio string) error {
 	return err
 }
 ```
+
+## Returning columns from inserted rows
+
+sqlc has full support for the `RETURNING` statement.
+
+```sql
+CREATE TABLE authors (
+  id         SERIAL PRIMARY KEY,
+  bio        text   NOT NULL
+);
+
+-- name: Delete :exec
+DELETE FROM authors WHERE id = $1;
+
+-- name: DeleteAffected :execrows
+DELETE FROM authors WHERE id = $1;
+
+-- name: DeleteID :one
+DELETE FROM authors WHERE id = $1
+RETURNING id;
+
+-- name: DeleteAuthor :one
+DELETE FROM authors WHERE id = $1
+RETURNING *;
+```
+
+```go
+package db
+
+import (
+	"context"
+	"database/sql"
+)
+
+type Author struct {
+	ID  int
+	Bio string
+}
+
+type DBTX interface {
+	ExecContext(context.Context, string, ...interface{}) error
+	QueryRowContext(context.Context, string, ...interface{}) error
+}
+
+func New(db DBTX) *Queries {
+	return &Queries{db: db}
+}
+
+type Queries struct {
+	db DBTX
+}
+
+const delete = `-- name: Delete :exec
+DELETE FROM authors WHERE id = $1
+`
+
+func (q *Queries) Delete(ctx context.Context, id int) error {
+	_, err := q.db.ExecContext(ctx, delete, id)
+	return err
+}
+
+const deleteAffected = `-- name: DeleteAffected :exec
+DELETE FROM authors WHERE id = $1
+`
+
+func (q *Queries) DeleteAffected(ctx context.Context, id int) (int64, error) {
+	result, err := q.db.ExecContext(ctx, deleteAffected, id)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const deleteID = `-- name: DeleteID :one
+DELETE FROM authors WHERE id = $1
+RETURNING id
+`
+
+func (q *Queries) DeleteID(ctx context.Context, id int) (int, error) {
+	row := q.db.QueryRowContext(ctx, deleteID, id)
+	var i int
+	err := row.Scan(&i)
+	return i, err
+}
+
+const deleteAuhtor = `-- name: DeleteAuthor :one
+DELETE FROM authors WHERE id = $1
+RETURNING id, bio
+`
+
+func (q *Queries) DeleteAuthor(ctx context.Context, id int) (Author, error) {
+	row := q.db.QueryRowContext(ctx, deleteAuhtor, id)
+	var i Author
+	err := row.Scan(&i.ID, &i.Bio)
+	return i, err
+}
+```

docs/howto/migrations.md renamed to docs/howto/ddl.md

@@ -1,4 +1,4 @@
-# Named parameters
+# Naming parameters
 
 sqlc tried to generate good names for positional parameters, but sometimes it
 lacks enough context. The following SQL generates parameters with less than