From a8b9de276c91a1508bb65adfb99b40541bd9d117 Mon Sep 17 00:00:00 2001 From: Kyle Conroy Date: Tue, 10 Aug 2021 22:23:24 -0700 Subject: [PATCH] docs: Update documentation (a bit) for v1.9.0 --- docs/conf.py | 2 +- docs/overview/install.md | 11 +- docs/reference/config.md | 4 +- docs/reference/language-support.rst | 13 +- docs/tutorials/getting-started.md | 198 ++++++++++++---------------- 5 files changed, 98 insertions(+), 130 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5db84ed289..b0786b3443 100644 --- a/docs/conf.py +++ b/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 --------------------------------------------------- diff --git a/docs/overview/install.md b/docs/overview/install.md index 34580cb549..ac02bc8a48 100644 --- a/docs/overview/install.md +++ b/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) diff --git a/docs/reference/config.md b/docs/reference/config.md index 26483ac9ea..79c702e8be 100644 --- a/docs/reference/config.md +++ b/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`: diff --git a/docs/reference/language-support.rst b/docs/reference/language-support.rst index 341f5317b1..de55489d6e 100644 --- a/docs/reference/language-support.rst +++ b/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 ************************ diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index a5f9f587dd..4cb2c2fc88 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -1,8 +1,31 @@ # 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 ( @@ -10,7 +33,11 @@ CREATE TABLE authors ( 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`.