From a17929e006ed1f9ee36e442695b43d90a7c85812 Mon Sep 17 00:00:00 2001 From: Nino Floris Date: Thu, 3 Oct 2024 20:01:45 +0200 Subject: [PATCH 1/2] Add 8.0 synchronous batching breaking change section --- conceptual/Npgsql/release-notes/8.0.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/conceptual/Npgsql/release-notes/8.0.md b/conceptual/Npgsql/release-notes/8.0.md index 5a9834b5..d38f500a 100644 --- a/conceptual/Npgsql/release-notes/8.0.md +++ b/conceptual/Npgsql/release-notes/8.0.md @@ -64,6 +64,26 @@ 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. This helps us prioritize the effort to bring back some mitigation in a patch version. + +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. + +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. + ### 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 or on : From 9ae93eba5d485bd484b1b2e00fb049de285015cc Mon Sep 17 00:00:00 2001 From: Nino Floris Date: Thu, 3 Oct 2024 20:08:39 +0200 Subject: [PATCH 2/2] Update 8.0.md Fix style issues --- conceptual/Npgsql/release-notes/8.0.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/conceptual/Npgsql/release-notes/8.0.md b/conceptual/Npgsql/release-notes/8.0.md index d38f500a..5bb4090b 100644 --- a/conceptual/Npgsql/release-notes/8.0.md +++ b/conceptual/Npgsql/release-notes/8.0.md @@ -71,15 +71,16 @@ To allow Npgsql to write command batches containing large data payloads (general 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. This helps us prioritize the effort to bring back some mitigation in a patch version. +* 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. 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. -Note: -We recommend using the asynchronous APIs for all scenarios. +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.