-
Notifications
You must be signed in to change notification settings - Fork 76
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.
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
Add 8.0 synchronous batching breaking change section #368
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
|
||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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>: | ||
|
There was a problem hiding this comment.
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.