diff --git a/docs/index.rst b/docs/index.rst index be4af64b42..0386a8175f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,7 +32,8 @@ code ever again. :caption: Tutorials :hidden: - tutorials/getting-started.md + tutorials/getting-started-mysql.md + tutorials/getting-started-postgresql.md .. toctree:: :maxdepth: 2 diff --git a/docs/tutorials/getting-started-mysql.md b/docs/tutorials/getting-started-mysql.md new file mode 100644 index 0000000000..fdb112d1c7 --- /dev/null +++ b/docs/tutorials/getting-started-mysql.md @@ -0,0 +1,155 @@ +# Getting started with MySQL + +This tutorial assumes that the latest version of sqlc is +[installed](../overview/install.html) and ready to use. + +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: "mysql" + 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 following contents: + +```sql +CREATE TABLE authors ( + id BIGINT NOT NULL AUTO_INCREMENT 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 = ? LIMIT 1; + +-- name: ListAuthors :many +SELECT * FROM authors +ORDER BY name; + +-- name: CreateAuthor :execresult +INSERT INTO authors ( + name, bio +) VALUES ( + ?, ? +); + +-- name: DeleteAuthor :exec +DELETE FROM authors +WHERE id = ?; +``` + +You are now ready to generate code. Run the `generate` command. You shouldn't see any errors or output. + +```shell +sqlc generate +``` + +You should now have a `db` package containing three files. + +``` +├── go.mod +├── query.sql +├── schema.sql +├── sqlc.yaml +└── tutorial + ├── db.go + ├── models.go + └── query.sql.go +``` + +You can use your newly generated queries in `app.go`. + +```go +package main + +import ( + "context" + "database/sql" + "log" + "reflect" + + "tutorial.sqlc.dev/app/tutorial" + + _ "github.com/go-sql-driver/mysql" +) + +func run() error { + ctx := context.Background() + + db, err := sql.Open("mysql", "user:password@/dbname") + if err != nil { + return err + } + + queries := tutorial.New(db) + + // list all authors + authors, err := queries.ListAuthors(ctx) + if err != nil { + return err + } + log.Println(authors) + + // create an author + result, 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 + } + + insertedAuthorID, err := result.LastInsertId() + if err != nil { + return err + } + log.Println(insertedAuthorID) + + // get the author we just inserted + fetchedAuthor, err := queries.GetAuthor(ctx, insertedAuthorID) + if err != nil { + return err + } + + // prints true + log.Println(reflect.DeepEqual(insertedAuthorID, fetchedAuthor.ID)) + return nil +} + +func main() { + if err := run(); err != nil { + log.Fatal(err) + } +} +``` + +Before the code will compile, you'll need to add the Go MySQL driver. + +``` +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`. diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started-postgresql.md similarity index 90% rename from docs/tutorials/getting-started.md rename to docs/tutorials/getting-started-postgresql.md index f1d3605b21..8e4a7bf188 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started-postgresql.md @@ -1,6 +1,7 @@ -# Getting started +# Getting started with PostgreSQL -This tutorial assumes that the latest version of sqlc is installed and ready to use. +This tutorial assumes that the latest version of sqlc is +[installed](../overview/install.html) and ready to use. Create a new directory called `sqlc-tutorial` and open it up. @@ -90,6 +91,8 @@ import ( "reflect" "tutorial.sqlc.dev/app/tutorial" + + _ "github.com/lib/pq" ) func run() error { @@ -137,5 +140,12 @@ func main() { } ``` +Before the code will compile, you'll need to add the Go PostgreSQL driver. + +``` +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`.