docs: Update getting started guides, use pgx for Postgres guide (#2891)

* docs: Update getting started guides, use pgx for Postgres guide * Update docs/reference/datatypes.md Co-authored-by: Kyle Gray <kyle@sqlc.dev> --------- Co-authored-by: Kyle Gray <kyle@sqlc.dev>
sqlc-dev · Oct 20, 2023 · bd9167e · bd9167e
1 parent 3754349
commit bd9167e
Show file tree

Hide file tree

Showing 4 changed files with 109 additions and 76 deletions.
diff --git a/docs/reference/datatypes.md b/docs/reference/datatypes.md
@@ -27,12 +27,16 @@ type Place struct {
 }
 ```
 
-## Dates and Time
+## Dates and times
 
-All PostgreSQL time and date types are returned as `time.Time` structs. For
+All date and time types are returned as `time.Time` structs. For
 null time or date values, the `NullTime` type from `database/sql` is used.
+
 The `pgx/v5` sql package uses the appropriate pgx types.
 
+For MySQL users relying on `github.com/go-sql-driver/mysql`, ensure that
+`parseTime=true` is added to your database connection string.
+
 ```sql
 CREATE TABLE authors (
   id         SERIAL    PRIMARY KEY,

diff --git a/docs/tutorials/getting-started-mysql.md b/docs/tutorials/getting-started-mysql.md
@@ -1,11 +1,13 @@
 # Getting started with MySQL
 
 This tutorial assumes that the latest version of sqlc is
-[installed](../overview/install.md) and ready to use.
+[installed](../overview/install.md) and ready to use. And we'll
+be generating Go code, but other
+[language plugins](../reference/language-support.rst) are available.
 
 Create a new directory called `sqlc-tutorial` and open it up.
 
-Initialize a new Go module named `tutorial.sql.dev/app`
+Initialize a new Go module named `tutorial.sqlc.dev/app`
 
 ```shell
 go mod init tutorial.sqlc.dev/app
@@ -16,7 +18,7 @@ directory. In our new directory, create a file named `sqlc.yaml` with the
 following contents:
 
 ```yaml
-version: 2
+version: "2"
 sql:
   - engine: "mysql"
     queries: "query.sql"
@@ -27,8 +29,9 @@ sql:
         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 (
@@ -61,13 +64,15 @@ DELETE FROM authors
 WHERE id = ?;
 ```
 
-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 output when you run
+the `generate` subcommand, unless something goes wrong:
 
 ```shell
 sqlc generate
 ```
 
-You should now have a `tutorial` package containing three files.
+You should now have a `tutorial` subdirectory with three files containing Go
+source code. These files comprise a Go package named `tutorial`:
 
 ```
 ├── go.mod
@@ -80,7 +85,8 @@ You should now have a `tutorial` package containing three files.
     └── query.sql.go
 ```
 
-You can use your newly generated queries in `app.go`.
+You can use your newly-generated `tutorial` package from any Go program.
+Create a file named `tutorial.go` and add the following contents:
 
 ```go
 package main
@@ -91,9 +97,9 @@ import (
 	"log"
 	"reflect"
 
-	"tutorial.sqlc.dev/app/tutorial"
-
 	_ "github.com/go-sql-driver/mysql"
+
+	"tutorial.sqlc.dev/app/tutorial"
 )
 
 func run() error {
@@ -146,17 +152,21 @@ func main() {
 }
 ```
 
-Before the code will compile, you'll need to add the Go MySQL driver.
+Before this code will compile you'll need to fetch the relevant MySQL driver:
 
-```
+```shell
 go get github.com/go-sql-driver/mysql
 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`.
+The program should compile without errors. To make that possible, sqlc generates
+readable, **idiomatic** Go code that you otherwise would've had to write
+yourself. Take a look in `tutorial/query.sql.go`.
+
+Of course for this program to run successfully you'll need
+to compile after replacing the database connection parameters in the call to
+`sql.Open()` with the correct parameters for your database. And your
+database must have the `authors` table as defined in `schema.sql`.
 
-If your tables have columns with date or time types, sqlc expects these values
-to scan into `time.Time` structs. If you're using
-`github.com/go-sql-driver/mysql`, ensure that `parseTime=true` has been added to
-the connection string.
+You should now have a working program using sqlc's generated Go source code,
+and hopefully can see how you'd use sqlc in your own real-world applications.
diff --git a/docs/tutorials/getting-started-postgresql.md b/docs/tutorials/getting-started-postgresql.md
@@ -1,11 +1,13 @@
 # Getting started with PostgreSQL
 
 This tutorial assumes that the latest version of sqlc is
-[installed](../overview/install.md) and ready to use.
+[installed](../overview/install.md) and ready to use. And we'll
+be generating Go code, but other
+[language plugins](../reference/language-support.rst) are available.
 
 Create a new directory called `sqlc-tutorial` and open it up.
 
-Initialize a new Go module named `tutorial.sqlc.dev/app`
+Initialize a new Go module named `tutorial.sqlc.dev/app`:
 
 ```shell
 go mod init tutorial.sqlc.dev/app
@@ -25,6 +27,7 @@ sql:
       go:
         package: "tutorial"
         out: "tutorial"
+        sql_package: "pgx/v5"
 ```
 
 sqlc needs to know your database schema and queries in order to generate code.
@@ -39,7 +42,7 @@ CREATE TABLE authors (
 );
 ```
 
-Next, create a `query.sql` file with the following four queries:
+Next, create a `query.sql` file with the following five queries:
 
 ```sql
 -- name: GetAuthor :one
@@ -58,23 +61,19 @@ INSERT INTO authors (
 )
 RETURNING *;
 
--- name: DeleteAuthor :exec
-DELETE FROM authors
-WHERE id = $1;
-```
-
-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
 WHERE id = $1;
+
+-- name: DeleteAuthor :exec
+DELETE FROM authors
+WHERE id = $1;
 ```
 
-Otherwise, to return the updated record to the user, add this to `query.sql`:
+If you prefer, you can alter the `UpdateAuthor` query to return the updated
+record:
 
 ```sql
 -- name: UpdateAuthor :one
@@ -85,13 +84,15 @@ WHERE id = $1
 RETURNING *;
 ```
 
-You are now ready to generate code. You shouldn't see any errors or output.
+You are now ready to generate code. You shouldn't see any output when you run
+the `generate` subcommand, unless something goes wrong:
 
 ```shell
 sqlc generate
 ```
 
-You should now have a `tutorial` package containing three files.
+You should now have a `tutorial` subdirectory with three files containing Go
+source code. These files comprise a Go package named `tutorial`:
 
 ```
 ├── go.mod
@@ -104,31 +105,33 @@ You should now have a `tutorial` package containing three files.
     └── query.sql.go
 ```
 
-You can use your newly generated queries in `app.go`.
+You can use your newly-generated `tutorial` package from any Go program.
+Create a file named `tutorial.go` and add the following contents:
 
 ```go
 package main
 
 import (
 	"context"
-	"database/sql"
 	"log"
 	"reflect"
 
-	"tutorial.sqlc.dev/app/tutorial"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgtype"
 
-	_ "github.com/lib/pq"
+	"tutorial.sqlc.dev/app/tutorial"
 )
 
 func run() error {
 	ctx := context.Background()
 
-	db, err := sql.Open("postgres", "user=pqgotest dbname=pqgotest sslmode=verify-full")
+	conn, err := pgx.Connect(ctx, "user=pqgotest dbname=pqgotest sslmode=verify-full")
 	if err != nil {
 		return err
 	}
+	defer conn.Close(ctx)
 
-	queries := tutorial.New(db)
+	queries := tutorial.New(conn)
 
 	// list all authors
 	authors, err := queries.ListAuthors(ctx)
@@ -140,7 +143,7 @@ func run() error {
 	// 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},
+		Bio:  pgtype.Text{String: "Co-author of The C Programming Language and The Go Programming Language", Valid: true},
 	})
 	if err != nil {
 		return err
@@ -165,13 +168,23 @@ func main() {
 }
 ```
 
-Before the code will compile, you'll need to add the Go PostgreSQL driver.
+Before this code will compile you'll need to fetch the relevant PostgreSQL
+driver. You can use `lib/pq` with the standard library's `database/sql`
+package, but in this tutorial we've used `pgx/v5`:
 
-```
-go get github.com/lib/pq
+```shell
+go get github.com/jackc/pgx/v5
 go build ./...
 ```
 
-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.
+The program should compile without errors. To make that possible, sqlc generates
+readable, **idiomatic** Go code that you otherwise would've had to write
+yourself. Take a look in `tutorial/query.sql.go`.
+
+Of course for this program to run successfully you'll need
+to compile after replacing the database connection parameters in the call to
+`pgx.Connect()` with the correct parameters for your database. And your
+database must have the `authors` table as defined in `schema.sql`.
+
+You should now have a working program using sqlc's generated Go source code,
+and hopefully can see how you'd use sqlc in your own real-world applications.