From 21bb1c354649e37aa84e6d00fe4e1d54041aed7e Mon Sep 17 00:00:00 2001 From: Kyle Conroy Date: Mon, 10 Apr 2023 02:47:43 -0700 Subject: [PATCH 1/3] docs: Add changelog for v1.18.0 --- docs/reference/changelog.md | 101 ++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index 1b6659fe41..69769307a0 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -1,6 +1,107 @@ # Changelog All notable changes to this project will be documented in this file. +## 1.18.0 +Released XXXX-XX-ZZ + +### Changes + +#### sqlc.embed + +Embedding allows you to reuse existing model structs in more queries, resulting +in less manual serilization work. First, imagine we have the following schema +with students and test scores. + + +```sql +CREATE TABLE students ( + id bigserial PRIMARY KEY, + name text, + age integer +) + +CREATE TABLE test_scores ( + student_id bigint, + score integer, + grade text +) +``` + +We want to select the student record and the highest score they got on a test. +Here's how we'd usually do that: + +```sql +-- name: HighScore :many +WITH high_scores AS ( + SELECT student_id, max(score) as high_score + FROM test_scores + GROUP BY 1 +) +SELECT students.*, high_score::integer +FROM students +JOIN high_scores ON high_scores.student_id = students.id; +``` + +When using Go, sqlc will produce a struct like + +``` +type HighScoreRow struct { + ID int64 + Name sql.NullString + Age sql.NullInt32 + HighScore int32 +} +``` + +```sql +-- name: HighScoreEmbed :many +WITH high_scores AS ( + SELECT student_id, max(score) as high_score + FROM test_scores + GROUP BY 1 +) +SELECT sqlc.embed(students), high_score::integer +FROM students +JOIN high_scores ON high_scores.student_id = students.id; +``` + +``` +type HighScoreRow struct { + Student Student + HighScore int32 +} +``` + +#### sqlc.slice + +#### Batch operation improvements + +When using batches with pgx, the error returned when a batch is closed is +exported by the generated package. This change allows for cleaner error +handling using `errors.Is`. + +```go +errors.Is(err, generated_package.ErrBatchAlreadyClosed) +``` + +Previously, you would have had to check match on the error message itself. + +``` +err.Error() == "batch already closed" +``` + +The generated code for batch operations always lived in `batch.go`. This file +name can now be configured via the `output_batch_file_name` configuration +option. + +#### Configurable query parameter limits for Go + +By default, sqlc will limit Go functions to a single parameter. If a query +includes more than one parameter, the generated method will use an argument +struct instead of positional arguments. This behavior can now be changed via +the `query_parameter_limit` configuration option. If set to `0`, every +genreated method will use a argument struct. + ## [1.17.2](https://github.com/kyleconroy/sqlc/releases/tag/1.17.2) Released 2023-02-22 From 2dda0d4ab7fc2cfbef13bb6f632dc559f4c4ef44 Mon Sep 17 00:00:00 2001 From: Kyle Conroy Date: Wed, 26 Apr 2023 10:22:34 -0700 Subject: [PATCH 2/3] Update changelog --- docs/reference/changelog.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index 69769307a0..5e5c395c48 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -8,6 +8,8 @@ Released XXXX-XX-ZZ #### sqlc.embed +_Developed by [@nickjackson](https://github.com/nickjackson)_ + Embedding allows you to reuse existing model structs in more queries, resulting in less manual serilization work. First, imagine we have the following schema with students and test scores. @@ -42,7 +44,7 @@ FROM students JOIN high_scores ON high_scores.student_id = students.id; ``` -When using Go, sqlc will produce a struct like +When using Go, sqlc will produce a struct like this: ``` type HighScoreRow struct { @@ -53,6 +55,9 @@ type HighScoreRow struct { } ``` +With embedding, the struct will contain a model for the table instead of a +flattened list of columns. + ```sql -- name: HighScoreEmbed :many WITH high_scores AS ( @@ -74,6 +79,25 @@ type HighScoreRow struct { #### sqlc.slice +_Developed by Paul Cameron and Jille Timmermans_ + +The MySQL Go driver does not support passing slices to the IN operator. The +`sqlc.slice` function generates a dynamic query at runtime with the correct +number of parameters. + +```sql +/* name: SelectStudents :many */ +SELECT * FROM students +WHERE age IN (sqlc.slice("ages")) +``` + +```go +func (q *Queries) SelectStudents(ctx context.Context, arges []int32) ([]Student, error) { +``` + +This feature is only supported in MySQL and cannot be used with prepared +queries. + #### Batch operation improvements When using batches with pgx, the error returned when a batch is closed is From daa3845e43023e778ba2557aa0d4b0f60cab68ac Mon Sep 17 00:00:00 2001 From: Kyle Conroy Date: Thu, 27 Apr 2023 10:14:10 -0700 Subject: [PATCH 3/3] docs: Add remote code generation --- docs/reference/changelog.md | 44 ++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index 5e5c395c48..031fc85538 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -2,10 +2,52 @@ All notable changes to this project will be documented in this file. ## 1.18.0 -Released XXXX-XX-ZZ +Released 2023-04-27 ### Changes +#### Remote code generation + +_Developed by [@andrewmbenton](https://github.com/andrewmbenton)_ + +At its core, sqlc is powered by SQL engines, which include parsers, formatters, +analyzers and more. While our goal is to support each engine on each operating +system, it's not always possible. For example, the PostgreSQL engine does not +work on Windows. + +To bridge that gap, we're announcing remote code generation, currently in +private alpha. To join the private alpha, [sign up for the waitlist](https://docs.google.com/forms/d/e/1FAIpQLScDWrGtTgZWKt3mdlF5R2XCX6tL1pMkB4yuZx5yq684tTNN1Q/viewform?usp=sf_link). + +To configure remote generation, configure a `cloud` block in `sqlc.json`. + +```json +{ + "version": "2", + "cloud": { + "organization": "", + "project": "", + }, + ... +} +``` + +You'll also need to the `SQLC_AUTH_TOKEN` environment variable. + +```bash +export SQLC_AUTH_TOKEN= +``` + +When the cloud configuration exists, `sqlc generate` will default to remote +generation. If you'd like to generate code locally, pass the `--no-remote` +option. + + +```bash +sqlc generate --no-remote +``` + +Remote generation is off by default and requires an opt-in to use. + #### sqlc.embed _Developed by [@nickjackson](https://github.com/nickjackson)_