Skip to content
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

Jump to bottom

Add 8.0 synchronous batching breaking change section #368

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add 8.0 synchronous batching breaking change section #368

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a17929e
Add 8.0 synchronous batching breaking change section
NinoFloris Oct 3, 2024
9ae93eb
Update 8.0.md
NinoFloris Oct 3, 2024
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
21 changes: 21 additions & 0 deletions conceptual/Npgsql/release-notes/8.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,27 @@ Version 8.0 contains many other smaller features and bug fixes, [see the 8.0.0 m

## Breaking changes

### Synchronous command batching can cause threadpool starvation

To allow Npgsql to write command batches containing large data payloads (generally parameter data) synchronously, without running into PostgreSQL limitations, it runs any commands after the first asynchronously. This introduces sync over async and can cause threadpool starvation at higher loads. In Npgsql versions prior to 8.0 a workaround was in place that would mitigate the effects of this sync over async, allowing most higher loads to run succesfully. This workaround was removed to make room for the far reaching NativeAOT refactor.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should probably add a few examples how threadpool starvation affects users, like delayed query execution time and even timeouts.


Affected APIs are the synchronous command execution methods: ExecuteReader, ExecuteNonQuery, ExecuteScalar in combination with a command batch (i.e. NpgsqlBatch or semicolon ';' concatenated commands).

If you are affected by this you can consider some of the following options:

* Use [ThreadPool.SetMinThreads()](https://learn.microsoft.com/en-us/dotnet/api/system.threading.threadpool.setminthreads?view=net-8.0) to expand the minimum pool of threads available for blocking.
* Refactor code using command batches to use asynchronous apis.

If these options are not suitable for your project you can consider opening an issue on [https://github.com/npgsql/npgsql](https://github.com/npgsql/npgsql). This helps us prioritize the effort to bring back some mitigation in a patch version.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe direct people to a specific issue (like the one that triggered this breaking change note) to avoid new duplicate issues getting opened etc.


To clarify, Npgsql 8.0 has not dropped support for synchronous command batches completely; the feature is entirely supported for use at low load or for local data exploration.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that maybe a bit too harsh? Given the workaround (e.g. SetMinThreads()) it's possible to do this even at higher load, it's just up to the user to preconfigure things etc?


Note:
We recommend using the asynchronous APIs for all scenarios.
Going forward existing and new functionality will see a reduced focus on having the synchronous API surface be as complete or as supported as its asynchronous counterpart. This is in line with broader .NET trends, including many modern building blocks — that would otherwise be useful to Npgsql — only support asynchronous use.

For 9.0 or later we're considering disabling synchronous I/O by default (see [https://github.com/npgsql/npgsql/issues/5865](https://github.com/npgsql/npgsql/issues/5865)). Add your comment there, describing your use-case, if you believe this change would force you to stay on an older version.

### <a name="dynamic-optin">JSON POCO and other dynamic features now require an explicit opt-in

Npgsql 8.0 is fully compatible with NativeAOT and trimming (see above). While most driver capabilities have been made to work in those profiles, certain features involve dynamic coding practices and are incompatible with NativeAOT and/or trimming - at least for now. As a result, these features now require explicit opt-ins (annotated to be incompatible with NativeAOT/trimming), which you must add either on your <xref:Npgsql.NpgsqlDataSourceBuilder> or on <xref:Npgsql.NpgsqlConnection.GlobalTypeMapper?displayProperty=nameWithType>:
Expand Down