Skip to content

Commit 6499625

Browse files
doron050doron050
authored
docs: move cancellation docs into docs/03_Usage.md so they survive README regeneration (#430)
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.
1 parent 0a688ee commit 6499625

2 files changed

Lines changed: 60 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ sql:
5151
| 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. | |
5252
| useCentralPackageManagement | default: `false`<br/>values: `false`,`true` | Yes | If true, the code is generated to support central package management. |
5353
| 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`). |
54-
| 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. |
54+
| 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. |
5555

5656
### Override option
5757
Override for a specific query:
@@ -255,6 +255,8 @@ we consider support for the different data types separately for batch inserts an
255255
| jsonpath | ✅ | ⚠️ |
256256
| xml | ✅ | ⚠️ |
257257
| enum | ✅ | ⚠️ |
258+
| any | ✅ | ❌ |
259+
| hstore | ✅ | ❌ |
258260

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

277+
*** `any` is a pseudo-type reported by sqlc when it cannot infer a column's type; it maps to `object` in C#.
278+
*** `hstore` is a key-value store type that maps to `object` in C#; readers use `GetValue()` to retrieve the value.
279+
275280
</details>
276281

277282
# MySQL
@@ -473,16 +478,34 @@ make test-wasm-plugin
473478
```
474479
475480
## Release flow
481+
476482
The release flow in this repo follows the semver conventions, building tag as `v[major].[minor].[patch]`.
477-
In order to create a release you need to add `[release]` somewhere in your commit message when merging to master.
478483
479-
### Version bumping (built on tags)
480-
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`.
481-
- Bump `minor` version by adding `[minor]` to your commit message resulting in a new tag with `v[major].[minor]+1.0` <br/>
482-
- Bump `major` version by adding `[major]` to your commit message resulting in a new tag with `v[major]+1.0.0` <br/>
484+
### PR Gate
485+
486+
Every PR that modifies source code, build configuration, or similar must be labeled with one of: `major`, `minor`, `patch`, or `skip-release`.
487+
488+
A bot posts a status check (`release-assistant/requirements`) that blocks merging until a version label is present.
489+
490+
### Generate Release PR
491+
492+
When Build completes on `main`, the `gen-release-pr.yml` workflow runs and:
493+
494+
1. Aggregates all unreleased, labeled PRs since the last release tag.
495+
2. Determines the release type from the labels (`major` > `minor` > `patch`).
496+
3. Computes the new version from the latest tag.
497+
4. Downloads the latest wasm artifact and computes its sha256.
498+
5. Regenerates documentation (README, quickstart) with the new version and wasm sha.
499+
6. Opens a `release-prep` PR with the regenerated docs.
500+
501+
### Release
502+
503+
When the `release-prep` PR is merged, `release.yml`:
483504
484-
### Release structure
485-
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/>
505+
1. Detects the `chore: prepare release vX` commit.
506+
2. Downloads the wasm artifact from the triggering Build.
507+
3. Reconstructs release notes from merged PR titles since the previous tag.
508+
4. Creates the release (with tag) and uploads the wasm asset.
486509
487510
# Examples
488511
<details>

‎docs/03_Usage.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
| 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. | |
1313
| useCentralPackageManagement | default: `false`<br/>values: `false`,`true` | Yes | If true, the code is generated to support central package management. |
1414
| 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`). |
15+
| 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. |
1516

1617
### Override option
1718
Override for a specific query:
@@ -118,3 +119,31 @@ public async Task ExampleTransaction(IDbConnection connection)
118119
```
119120

120121
More info can be found in [here](https://docs.sqlc.dev/en/stable/howto/transactions.html).
122+
123+
### Cancellation
124+
Set `withCancellationToken: true` to make every generated method accept an optional
125+
`CancellationToken`. The token is threaded into every async database call, so a cancelled
126+
token interrupts the in-flight query and releases the locks that statement holds. The
127+
option is off by default; when off, generated output is identical to before.
128+
129+
```C#
130+
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
131+
try
132+
{
133+
var author = await queries.GetAuthor(authorId, cts.Token);
134+
}
135+
catch (OperationCanceledException)
136+
{
137+
// the query was cancelled; its statement-level locks are released
138+
}
139+
```
140+
141+
Notes:
142+
- **PostgreSQL & MySQL** interrupt the running statement server-side (Npgsql sends a cancel
143+
request; MySqlConnector issues `KILL QUERY`), releasing that statement's locks immediately.
144+
- **SQLite** runs synchronously and only honours the token *before* the statement starts;
145+
an already-running SQLite statement is not interrupted.
146+
- **Transactions:** cancelling a query inside a `WithTransaction(...)` flow releases only that
147+
statement's locks. Locks held by earlier statements in the transaction (and, on PostgreSQL,
148+
the aborted-transaction state) are released when **you** roll back — the generated code never
149+
rolls back for you.

0 commit comments

Comments
 (0)