diff --git a/docs/reference/datatypes.md b/docs/reference/datatypes.md index 80b35bbfe6..542624a25e 100644 --- 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 index 4fa55d713c..78f06b7c65 100644 --- 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 index 9f7d09a1a4..13cd7a8a81 100644 --- 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. diff --git a/docs/tutorials/getting-started-sqlite.md b/docs/tutorials/getting-started-sqlite.md index 28f0669ea3..6f8feefd69 100644 --- a/docs/tutorials/getting-started-sqlite.md +++ b/docs/tutorials/getting-started-sqlite.md @@ -1,11 +1,13 @@ # Getting started with SQLite 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,19 +18,20 @@ directory. In our new directory, create a file named `sqlc.yaml` with the following contents: ```yaml -version: 2 +version: "2" sql: - engine: "sqlite" - schema: "schema.sql" 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 ( @@ -38,7 +41,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 @@ -57,22 +60,19 @@ INSERT INTO authors ( ) RETURNING *; --- name: DeleteAuthor :exec -DELETE FROM authors -WHERE id = ?; -``` - -For SQL UPDATE if you do not want to return the updated record to the user, add this to the `query.sql` file: - -```sql -- name: UpdateAuthor :exec UPDATE authors set name = ?, bio = ? WHERE id = ?; + +-- name: DeleteAuthor :exec +DELETE FROM authors +WHERE id = ?; ``` -Otherwise, to return the updated record back to the user, add this to the `query.sql` file: +If you prefer, you can alter the `UpdateAuthor` query to return the updated +record: ```sql -- name: UpdateAuthor :one @@ -83,13 +83,15 @@ WHERE id = ? 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 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 @@ -102,7 +104,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 @@ -110,14 +113,13 @@ package main import ( "context" "database/sql" + _ "embed" "log" "reflect" - "tutorial.sqlc.dev/app/tutorial" - - _ "embed" - _ "github.com/mattn/go-sqlite3" + + "tutorial.sqlc.dev/app/tutorial" ) //go:embed schema.sql @@ -173,12 +175,16 @@ func main() { } ``` -Before the code will compile, you'll need to add the Go SQLite driver. +Before this code will compile you'll need to fetch the relevant SQLite driver: -``` -go mod tidy +```shell +go get github.com/mattn/go-sqlite3 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, and run successfully. 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`. + +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.