docs: Update documentation (a bit) for v1.9.0 (#1117)

docs/conf.py

@@ -22,7 +22,7 @@
 author = 'Kyle Conroy'
 
 # The full version, including alpha/beta/rc tags
-release = '1.6.0'
+release = '1.9.0'
 
 
 # -- General configuration ---------------------------------------------------

docs/overview/install.md

@@ -34,11 +34,8 @@ docker run --rm -v $(pwd):/src -w /src kjconroy/sqlc generate
 
 ## Downloads
 
-Get pre-built binaries for *v1.8.0*:
+Get pre-built binaries for *v1.9.0*:
 
-- [Linux](https://github.com/kyleconroy/sqlc/releases/download/v1.8.0/sqlc-v1.8.0-linux-amd64.tar.gz)
-- [macOS](https://github.com/kyleconroy/sqlc/releases/download/v1.8.0/sqlc-v1.8.0-darwin-amd64.zip)
-- [Windows (MySQL only)](https://github.com/kyleconroy/sqlc/releases/download/v1.8.0/sqlc-v1.8.0-windows-amd64.zip)
-
-Binaries for a specific release can be downloaded on
-[GitHub](https://github.com/kyleconroy/sqlc/releases).
+- [Linux](https://github.com/kyleconroy/sqlc/releases/download/v1.9.0/sqlc_1.9.0_linux_amd64.tar.gz)
+- [macOS](https://github.com/kyleconroy/sqlc/releases/download/v1.9.0/sqlc_1.9.0_darwin_amd64.zip)
+- [Windows (MySQL only)](https://github.com/kyleconroy/sqlc/releases/download/v1.9.0/sqlc_1.9.0_windows_amd64.zip)

docs/reference/config.md

@@ -33,7 +33,9 @@ Each package document has the following keys:
 - `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
+  - Either `postgresql` or `mysql`. Defaults to `postgresql`.
+- `sql_package`:
+  - Either `pgx/v4` or `database/sql`. Defaults to `database/sql`.
 - `emit_db_tags`:
   - If true, add DB tags to generated structs. Defaults to `false`.
 - `emit_prepared_queries`:

docs/reference/language-support.rst

@@ -1,12 +1,13 @@
 Database and Language Support
 #############################
 
-========  ======  ==========
-Language  MySQL   PostgreSQL
---------  ------  ----------
-Go        Stable  Stable
-Kotlin    Beta    Beta
-========  ======  ==========
+========  ======        ==========
+Language  MySQL         PostgreSQL
+--------  ------        ----------
+Go        Stable        Stable
+Kotlin    Beta          Beta
+Python    Experimental  Experimental
+========  ============  ==========
 
 Planned Language Support
 ************************

docs/tutorials/getting-started.md

@@ -1,16 +1,43 @@
 # Getting started
 
-Okay, enough hype, let's see it in action.
+This tutorial assumes that the latest version of sqlc is installed and ready to use.
 
-First you pass the following SQL to `sqlc generate`:
+Create a new directory called `sqlc-tutorial` and open it up.
+
+Initialize a new Go module named `tutorial.sql.dev/app`
+
+```shell
+go mod init tutorial.sqlc.dev/app
+```
+
+sqlc looks for either a `sqlc.yaml` or `sqlc.json` file in the current
+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"
+```
+
+sqlc needs to know your database schema and queries. In the same directory,
+create a file named `schema.sql` with the fullowing contents:
 
 ```sql
 CREATE TABLE authors (
   id   BIGSERIAL PRIMARY KEY,
   name text      NOT NULL,
   bio  text
 );
+```
+
+Next, create a `query.sql` file with the following four queries:
 
+```sql
 -- name: GetAuthor :one
 SELECT * FROM authors
 WHERE id = $1 LIMIT 1;
@@ -32,142 +59,83 @@ DELETE FROM authors
 WHERE id = $1;
 ```
 
-And then in your application code you'd write:
+You are now ready to generate code. Run the `generate` command. You shouldn't see any errors or output.
 
-```go
+```shell
+sqlc generate
+```
 
-// list all authors
-authors, err := db.ListAuthors(ctx)
-if err != nil {
-    return err
-}
-fmt.Println(authors)
-
-// create an author
-insertedAuthor, err := db.CreateAuthor(ctx, db.CreateAuthorParams{
-        Name: "Brian Kernighan",
-        Bio:  sql.NullString{String: "Co-author of The C Programming Language and The Go Programming Language", Valid: true},
-})
-if err != nil {
-        return err
-}
-fmt.Println(insertedAuthor)
+You should now have a `db` package containing three files.
 
-// get the author we just inserted
-fetchedAuthor, err := db.GetAuthor(ctx, insertedAuthor.ID)
-if err != nil {
-        return err
-}
-// prints true
-fmt.Println(reflect.DeepEqual(insertedAuthor, fetchedAuthor))
+```
+├── go.mod
+├── query.sql
+├── schema.sql
+├── sqlc.yaml
+└── tutorial
+    ├── db.go
+    ├── models.go
+    └── query.sql.go
 ```
 
-To make that possible, sqlc generates readable, **idiomatic** Go code that you
-otherwise would have had to write yourself. Take a look:
+You can use your newly generated queries in `app.go`.
 
 ```go
-package db
+package main
 
 import (
 	"context"
 	"database/sql"
-)
-
-type Author struct {
-	ID   int64
-	Name string
-	Bio  sql.NullString
-}
+	"log"
+	"reflect"
 
-const createAuthor = `-- name: CreateAuthor :one
-INSERT INTO authors (
-  name, bio
-) VALUES (
-  $1, $2
+	"tutorial.sqlc.dev/app/tutorial"
 )
-RETURNING id, name, bio
-`
-
-type CreateAuthorParams struct {
-	Name string
-	Bio  sql.NullString
-}
 
-func (q *Queries) CreateAuthor(ctx context.Context, arg CreateAuthorParams) (Author, error) {
-	row := q.db.QueryRowContext(ctx, createAuthor, arg.Name, arg.Bio)
-	var i Author
-	err := row.Scan(&i.ID, &i.Name, &i.Bio)
-	return i, err
-}
+func run() error {
+	ctx := context.Background()
 
-const deleteAuthor = `-- name: DeleteAuthor :exec
-DELETE FROM authors
-WHERE id = $1
-`
-
-func (q *Queries) DeleteAuthor(ctx context.Context, id int64) error {
-	_, err := q.db.ExecContext(ctx, deleteAuthor, id)
-	return err
-}
-
-const getAuthor = `-- name: GetAuthor :one
-SELECT id, name, bio FROM authors
-WHERE id = $1 LIMIT 1
-`
-
-func (q *Queries) GetAuthor(ctx context.Context, id int64) (Author, error) {
-	row := q.db.QueryRowContext(ctx, getAuthor, id)
-	var i Author
-	err := row.Scan(&i.ID, &i.Name, &i.Bio)
-	return i, err
-}
+	db, err := sql.Open("postgres", "user=pqgotest dbname=pqgotest sslmode=verify-full")
+	if err != nil {
+		return err
+	}
 
-const listAuthors = `-- name: ListAuthors :many
-SELECT id, name, bio FROM authors
-ORDER BY name
-`
+	queries := tutorial.New(db)
 
-func (q *Queries) ListAuthors(ctx context.Context) ([]Author, error) {
-	rows, err := q.db.QueryContext(ctx, listAuthors)
-	 if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-	var items []Author
-	for rows.Next() {
-		var i Author
-		if err := rows.Scan(&i.ID, &i.Name, &i.Bio); err != nil {
-			 return nil, err
-		}
-		items = append(items, i)
-	}
-	if err := rows.Close(); err != nil {
-		return nil, err
+	// list all authors
+	authors, err := queries.ListAuthors(ctx)
+	if err != nil {
+		return err
 	}
-	if err := rows.Err(); err != nil {
-		return nil, err
+	log.Println(authors)
+
+	// create an author
+	insertedAuthor, err := queries.CreateAuthor(ctx, tutorial.CreateAuthorParams{
+		Name: "Brian Kernighan",
+		Bio:  sql.NullString{String: "Co-author of The C Programming Language and The Go Programming Language", Valid: true},
+	})
+	if err != nil {
+		return err
 	}
-	return items, nil
-}
-
-type DBTX interface {
-	ExecContext(context.Context, string, ...interface{}) (sql.Result, error)
-	PrepareContext(context.Context, string) (*sql.Stmt, error)
-	QueryContext(context.Context, string, ...interface{}) (*sql.Rows, error)
-	QueryRowContext(context.Context, string, ...interface{}) *sql.Row
-}
+	log.Println(insertedAuthor)
 
-func New(db DBTX) *Queries {
-	return &Queries{db: db}
-}
+	// get the author we just inserted
+	fetchedAuthor, err := queries.GetAuthor(ctx, insertedAuthor.ID)
+	if err != nil {
+		return err
+	}
 
-type Queries struct {
-	db DBTX
+	// prints true
+	log.Println(reflect.DeepEqual(insertedAuthor, fetchedAuthor))
+	return nil
 }
 
-func (q *Queries) WithTx(tx *sql.Tx) *Queries {
-	return &Queries{
-		db: tx,
+func main() {
+	if err := run(); err != nil {
+		log.Fatal(err)
 	}
 }
 ```
+
+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`.