Skip to content

fix: move cancellation docs into docs/ so they survive README regeneration #430

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
doron050 merged 1 commit into from
Jul 25, 2026
Merged

fix: move cancellation docs into docs/ so they survive README regeneration #430

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 31 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ sql:
| Override | values: A nested override value like [this](#override-option). | Yes | Allows you to override the generated C# data types for specific columns in specific queries. This option accepts a `query_name:column_name` mapping and the overriden data type. | |
| useCentralPackageManagement | default: `false`<br/>values: `false`,`true` | Yes | If true, the code is generated to support central package management. |
| withAsyncSuffix | default: `true`<br/>values: `false`,`true` | Yes | When true, async methods will have the "Async" suffix appended to their names (e.g., `GetAuthorAsync`). When false, async methods will not have the suffix (e.g., `GetAuthor`). |
| withCancellationToken | default: `false`<br/>values: `false`,`true` | Yes | When true, every generated method takes an optional trailing `CancellationToken cancellationToken = default`, threaded into every async DB call so in-flight queries can be cancelled. See [Cancellation](#cancellation). When false (default), generated output is unchanged. |
| withCancellationToken | default: `false`<br/>values: `false`,`true` | Yes | When true, every generated method takes an optional trailing `CancellationToken cancellationToken = default`, threaded into every async DB call so in-flight queries can be cancelled. See [Cancellation](#cancellation). When false (default), generated output is unchanged. |

### Override option
Override for a specific query:
Expand Down Expand Up @@ -255,6 +255,8 @@ we consider support for the different data types separately for batch inserts an
| jsonpath | ✅ | ⚠️ |
| xml | ✅ | ⚠️ |
| enum | ✅ | ⚠️ |
| any | ✅ | ❌ |
| hstore | ✅ | ❌ |

*** `time with time zone` is not useful and not recommended to use by Postgres themselves -
see [here](https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-DATETIME) -
Expand All @@ -272,6 +274,9 @@ An example of this conversion:
INSERT INTO tab1 (macaddr8_field) VALUES (sqlc.narg('macaddr8_field')::macaddr8);
```

*** `any` is a pseudo-type reported by sqlc when it cannot infer a column's type; it maps to `object` in C#.
*** `hstore` is a key-value store type that maps to `object` in C#; readers use `GetValue()` to retrieve the value.

</details>

# MySQL
Expand Down Expand Up @@ -473,16 +478,34 @@ make test-wasm-plugin
```

## Release flow

The release flow in this repo follows the semver conventions, building tag as `v[major].[minor].[patch]`.
In order to create a release you need to add `[release]` somewhere in your commit message when merging to master.

### Version bumping (built on tags)
By default, the release script will bump the patch version. Adding `[release]` to your commit message results in a new tag with `v[major].[minor].[patch]+1`.
- Bump `minor` version by adding `[minor]` to your commit message resulting in a new tag with `v[major].[minor]+1.0` <br/>
- Bump `major` version by adding `[major]` to your commit message resulting in a new tag with `v[major]+1.0.0` <br/>
### PR Gate

Every PR that modifies source code, build configuration, or similar must be labeled with one of: `major`, `minor`, `patch`, or `skip-release`.

A bot posts a status check (`release-assistant/requirements`) that blocks merging until a version label is present.

### Generate Release PR

When Build completes on `main`, the `gen-release-pr.yml` workflow runs and:

1. Aggregates all unreleased, labeled PRs since the last release tag.
2. Determines the release type from the labels (`major` > `minor` > `patch`).
3. Computes the new version from the latest tag.
4. Downloads the latest wasm artifact and computes its sha256.
5. Regenerates documentation (README, quickstart) with the new version and wasm sha.
6. Opens a `release-prep` PR with the regenerated docs.

### Release

When the `release-prep` PR is merged, `release.yml`:

### Release structure
The new created tag will create a draft release with it, in the release there will be the wasm plugin embedded in the release. <br/>
1. Detects the `chore: prepare release vX` commit.
2. Downloads the wasm artifact from the triggering Build.
3. Reconstructs release notes from merged PR titles since the previous tag.
4. Creates the release (with tag) and uploads the wasm asset.

# Examples
<details>
Expand Down
29 changes: 29 additions & 0 deletions docs/03_Usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
| Override | values: A nested override value like [this](#override-option). | Yes | Allows you to override the generated C# data types for specific columns in specific queries. This option accepts a `query_name:column_name` mapping and the overriden data type. | |
| useCentralPackageManagement | default: `false`<br/>values: `false`,`true` | Yes | If true, the code is generated to support central package management. |
| withAsyncSuffix | default: `true`<br/>values: `false`,`true` | Yes | When true, async methods will have the "Async" suffix appended to their names (e.g., `GetAuthorAsync`). When false, async methods will not have the suffix (e.g., `GetAuthor`). |
| withCancellationToken | default: `false`<br/>values: `false`,`true` | Yes | When true, every generated method takes an optional trailing `CancellationToken cancellationToken = default`, threaded into every async DB call so in-flight queries can be cancelled. See [Cancellation](#cancellation). When false (default), generated output is unchanged. |

### Override option
Override for a specific query:
Expand Down Expand Up @@ -118,3 +119,31 @@ public async Task ExampleTransaction(IDbConnection connection)
```

More info can be found in [here](https://docs.sqlc.dev/en/stable/howto/transactions.html).

### Cancellation
Set `withCancellationToken: true` to make every generated method accept an optional
`CancellationToken`. The token is threaded into every async database call, so a cancelled
token interrupts the in-flight query and releases the locks that statement holds. The
option is off by default; when off, generated output is identical to before.

```C#
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
try
{
var author = await queries.GetAuthor(authorId, cts.Token);
}
catch (OperationCanceledException)
{
// the query was cancelled; its statement-level locks are released
}
```

Notes:
- **PostgreSQL & MySQL** interrupt the running statement server-side (Npgsql sends a cancel
request; MySqlConnector issues `KILL QUERY`), releasing that statement's locks immediately.
- **SQLite** runs synchronously and only honours the token *before* the statement starts;
an already-running SQLite statement is not interrupted.
- **Transactions:** cancelling a query inside a `WithTransaction(...)` flow releases only that
statement's locks. Locks held by earlier statements in the transaction (and, on PostgreSQL,
the aborted-transaction state) are released when **you** roll back — the generated code never
rolls back for you.
Loading