|
| 1 | +# Getting started with YDB |
| 2 | + |
| 3 | +This tutorial assumes that the latest version of sqlc is |
| 4 | +[installed](../overview/install.md) and ready to use. |
| 5 | + |
| 6 | +We'll generate Go code here, but other |
| 7 | +[language plugins](../reference/language-support.rst) are available. You'll |
| 8 | +naturally need the Go toolchain if you want to build and run a program with the |
| 9 | +code sqlc generates, but sqlc itself has no dependencies. |
| 10 | + |
| 11 | +At the end, you'll push your SQL queries to [sqlc |
| 12 | +Cloud](https://dashboard.sqlc.dev/) for further insights and analysis. |
| 13 | + |
| 14 | +## Setting up |
| 15 | + |
| 16 | +Create a new directory called `sqlc-tutorial` and open it up. |
| 17 | + |
| 18 | +Initialize a new Go module named `tutorial.sqlc.dev/app`: |
| 19 | + |
| 20 | +```shell |
| 21 | +go mod init tutorial.sqlc.dev/app |
| 22 | +``` |
| 23 | + |
| 24 | +sqlc looks for either a `sqlc.(yaml|yml)` or `sqlc.json` file in the current |
| 25 | +directory. In our new directory, create a file named `sqlc.yaml` with the |
| 26 | +following contents: |
| 27 | + |
| 28 | +```yaml |
| 29 | +version: "2" |
| 30 | +sql: |
| 31 | + - engine: "ydb" |
| 32 | + queries: "query.sql" |
| 33 | + schema: "schema.sql" |
| 34 | + gen: |
| 35 | + go: |
| 36 | + package: "tutorial" |
| 37 | + out: "tutorial" |
| 38 | +``` |
| 39 | +
|
| 40 | +## Schema and queries |
| 41 | +
|
| 42 | +sqlc needs to know your database schema and queries in order to generate code. |
| 43 | +In the same directory, create a file named `schema.sql` with the following |
| 44 | +content: |
| 45 | + |
| 46 | +```sql |
| 47 | +CREATE TABLE authors ( |
| 48 | + id Serial, |
| 49 | + name Text NOT NULL, |
| 50 | + bio Text, |
| 51 | + PRIMARY KEY (id) |
| 52 | +); |
| 53 | +``` |
| 54 | + |
| 55 | +Next, create a `query.sql` file with the following five queries: |
| 56 | + |
| 57 | +```sql |
| 58 | +-- name: GetAuthor :one |
| 59 | +SELECT * FROM authors |
| 60 | +WHERE id = $id LIMIT 1; |
| 61 | +
|
| 62 | +-- name: ListAuthors :many |
| 63 | +SELECT * FROM authors |
| 64 | +ORDER BY name; |
| 65 | +
|
| 66 | +-- name: CreateOrUpdateAuthor :one |
| 67 | +UPSERT INTO authors (name, bio) |
| 68 | +VALUES ( |
| 69 | + $name, $bio |
| 70 | +) |
| 71 | +RETURNING *; |
| 72 | +
|
| 73 | +-- name: DeleteAuthor :exec |
| 74 | +DELETE FROM authors WHERE id = $id; |
| 75 | +
|
| 76 | +-- name: DropTable :exec |
| 77 | +DROP TABLE IF EXISTS authors; |
| 78 | +``` |
| 79 | + |
| 80 | +Note that YDB uses named parameters (`$id`, `$name`, `$bio`) rather than |
| 81 | +positional parameters. |
| 82 | + |
| 83 | +## Generating code |
| 84 | + |
| 85 | +You are now ready to generate code. You shouldn't see any output when you run |
| 86 | +the `generate` subcommand, unless something goes wrong: |
| 87 | + |
| 88 | +```shell |
| 89 | +sqlc generate |
| 90 | +``` |
| 91 | + |
| 92 | +You should now have a `tutorial` subdirectory with three files containing Go |
| 93 | +source code. These files comprise a Go package named `tutorial`: |
| 94 | + |
| 95 | +``` |
| 96 | +├── go.mod |
| 97 | +├── query.sql |
| 98 | +├── schema.sql |
| 99 | +├── sqlc.yaml |
| 100 | +└── tutorial |
| 101 | + ├── db.go |
| 102 | + ├── models.go |
| 103 | + └── query.sql.go |
| 104 | +``` |
| 105 | + |
| 106 | +## Using generated code |
| 107 | + |
| 108 | +You can use your newly-generated `tutorial` package from any Go program. |
| 109 | +Create a file named `tutorial.go` and add the following contents: |
| 110 | + |
| 111 | +```go |
| 112 | +package main |
| 113 | +
|
| 114 | +import ( |
| 115 | + "context" |
| 116 | + "log" |
| 117 | +
|
| 118 | + "github.com/ydb-platform/ydb-go-sdk/v3" |
| 119 | + "github.com/ydb-platform/ydb-go-sdk/v3/query" |
| 120 | +
|
| 121 | + "tutorial.sqlc.dev/app/tutorial" |
| 122 | +) |
| 123 | +
|
| 124 | +func ptr(s string) *string { |
| 125 | + return &s |
| 126 | +} |
| 127 | +
|
| 128 | +func run() error { |
| 129 | + ctx := context.Background() |
| 130 | +
|
| 131 | + // Create YDB connection |
| 132 | + // Replace with your actual YDB endpoint |
| 133 | + db, err := ydb.Open(ctx, "grpcs://localhost:2136/local") |
| 134 | + if err != nil { |
| 135 | + return err |
| 136 | + } |
| 137 | + defer db.Close(ctx) |
| 138 | +
|
| 139 | + queries := tutorial.New(db.Query()) |
| 140 | +
|
| 141 | + // list all authors |
| 142 | + authors, err := queries.ListAuthors(ctx) |
| 143 | + if err != nil { |
| 144 | + return err |
| 145 | + } |
| 146 | + log.Println(authors) |
| 147 | +
|
| 148 | + // create an author |
| 149 | + insertedAuthor, err := queries.CreateOrUpdateAuthor(ctx, tutorial.CreateOrUpdateAuthorParams{ |
| 150 | + Name: "Brian Kernighan", |
| 151 | + Bio: ptr("Co-author of The C Programming Language and The Go Programming Language"), |
| 152 | + }, query.WithIdempotent()) |
| 153 | + if err != nil { |
| 154 | + return err |
| 155 | + } |
| 156 | + log.Println(insertedAuthor) |
| 157 | +
|
| 158 | + // get the author we just inserted |
| 159 | + fetchedAuthor, err := queries.GetAuthor(ctx, insertedAuthor.ID) |
| 160 | + if err != nil { |
| 161 | + return err |
| 162 | + } |
| 163 | + log.Println(fetchedAuthor) |
| 164 | + return nil |
| 165 | +} |
| 166 | +
|
| 167 | +func main() { |
| 168 | + if err := run(); err != nil { |
| 169 | + log.Fatal(err) |
| 170 | + } |
| 171 | +} |
| 172 | +``` |
| 173 | + |
| 174 | +Before this code will compile you'll need to fetch the relevant YDB driver: |
| 175 | + |
| 176 | +```shell |
| 177 | +go get github.com/ydb-platform/ydb-go-sdk/v3 |
| 178 | +go build ./... |
| 179 | +``` |
| 180 | + |
| 181 | +The program should compile without errors. To make that possible, sqlc generates |
| 182 | +readable, **idiomatic** Go code that you otherwise would've had to write |
| 183 | +yourself. Take a look in `tutorial/query.sql.go`. |
| 184 | + |
| 185 | +Of course for this program to run successfully you'll need |
| 186 | +to compile after replacing the database connection parameters in the call to |
| 187 | +`ydb.Open()` with the correct parameters for your database. And your |
| 188 | +database must have the `authors` table as defined in `schema.sql`. |
| 189 | + |
| 190 | +You should now have a working program using sqlc's generated Go source code, |
| 191 | +and hopefully can see how you'd use sqlc in your own real-world applications. |
| 192 | + |
| 193 | +## Query verification (Not supported for YDB yet) |
| 194 | + |
| 195 | +[sqlc Cloud](https://dashboard.sqlc.dev) provides additional verification, catching subtle bugs. To get started, create a |
| 196 | +[dashboard account](https://dashboard.sqlc.dev). Once you've signed in, create a |
| 197 | +project and generate an auth token. Add your project's ID to the `cloud` block |
| 198 | +to your sqlc.yaml. |
| 199 | + |
| 200 | +```yaml |
| 201 | +version: "2" |
| 202 | +cloud: |
| 203 | + # Replace <PROJECT_ID> with your project ID from the sqlc Cloud dashboard |
| 204 | + project: "<PROJECT_ID>" |
| 205 | +sql: |
| 206 | + - engine: "ydb" |
| 207 | + queries: "query.sql" |
| 208 | + schema: "schema.sql" |
| 209 | + gen: |
| 210 | + go: |
| 211 | + package: "tutorial" |
| 212 | + out: "tutorial" |
| 213 | +``` |
| 214 | + |
| 215 | +Replace `<PROJECT_ID>` with your project ID from the sqlc Cloud dashboard. It |
| 216 | +will look something like `01HA8SZH31HKYE9RR3N3N3TSJM`. |
| 217 | + |
| 218 | +And finally, set the `SQLC_AUTH_TOKEN` environment variable: |
| 219 | + |
| 220 | +```shell |
| 221 | +export SQLC_AUTH_TOKEN="<your sqlc auth token>" |
| 222 | +``` |
| 223 | + |
| 224 | +```shell |
| 225 | +$ sqlc push --tag tutorial |
| 226 | +``` |
| 227 | + |
| 228 | +In the sidebar, go to the "Queries" section to see your published queries. Run |
| 229 | +`verify` to ensure that previously published queries continue to work against |
| 230 | +updated database schema. |
| 231 | + |
| 232 | +```shell |
| 233 | +$ sqlc verify --against tutorial |
| 234 | +``` |
0 commit comments