From 3d04164f382e525a49016c5ecfc2d372b21e6968 Mon Sep 17 00:00:00 2001 From: Doron Eli Rachman Date: Sat, 25 Jul 2026 14:09:02 +0300 Subject: [PATCH] docs: move cancellation docs into docs/03_Usage.md so they survive README regeneration The cancellation documentation (withCancellationToken option and Cancellation section) was added directly to README.md in PR #420. However, README.md is auto-generated by concatenating docs/0*.md files via generate_all_docs.sh. When the release prep workflow regenerates the README, the cancellation content gets lost because it lives only in README.md itself. Fix: move the content into docs/03_Usage.md (the Usage doc where the options table and transactions section live), then regenerate README.md from the docs. --- README.md | 39 +++++++++++++++++++++++++++++++-------- docs/03_Usage.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ebf22240..dab34096 100644 --- a/README.md +++ b/README.md @@ -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`
values: `false`,`true` | Yes | If true, the code is generated to support central package management. | | withAsyncSuffix | default: `true`
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`
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`
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: @@ -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) - @@ -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. + # MySQL @@ -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`
-- Bump `major` version by adding `[major]` to your commit message resulting in a new tag with `v[major]+1.0.0`
+### 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.
+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
diff --git a/docs/03_Usage.md b/docs/03_Usage.md index eff9f101..7b35281c 100644 --- a/docs/03_Usage.md +++ b/docs/03_Usage.md @@ -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`
values: `false`,`true` | Yes | If true, the code is generated to support central package management. | | withAsyncSuffix | default: `true`
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`
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: @@ -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.