Release notes for Npgsql 10

Author: vonzshik

conceptual/Npgsql/diagnostics/tracing.md

@@ -50,9 +50,10 @@ dataSourceBuilder.ConfigureTracing(o => o
 This allows you to:
 
 * Specify a filter which determines which commands get traced
-* Set the the tracing span name (e.g. use the command's SQL as the span name)
+* Set the tracing span name (e.g. use the command's SQL as the span name)
 * Add arbitrary tags to the tracing span, based on the command
 * Disable the time-to-first-read event that's emitted in spans
+* Disable tracing physical connection open span
 
 ## Using `AsyncLocal` to pass arbitrary information to your callbacks
 

conceptual/Npgsql/release-notes/10.0.md

@@ -3,8 +3,48 @@
 Npgsql version 10.0 is now in development, preview versions are available on [nuget.org](https://www.nuget.org/packages/Npgsql).
 
 > [!NOTE]
-> The 10.0 release notes will be published soon.
+> We're considering to start dropping support for synchronous APIs (`NpgsqlConnection.Open`, `NpgsqlCommand.ExecuteNonQuery`, etc.) starting with Npgsql 11.0. The current plan is to deprecate the API by throwing a runtime exception by default (with a switch to re-enable synchronous I/O) for Npgsql 11.0, while possibly completely removing it for Npgsql 12.0. This is in line with ASP.NET Core and .NET APIs in general, which are moving in the direction of async I/O only (for example, `System.IO.Pipelines` doesn't have synchronous I/O). If you have any questions or want to share you experience/issues with async I/O, please feel free to post in the [issue](https://github.com/npgsql/npgsql/issues/5865).
+
+While this is a relatively minor release in terms of changes, it does contain new features and improvements. Notable changes:
+
+## GSSAPI session encryption
+
+GSSAPI session encryption is an alternative to SSL/TLS session encryption, where special temporary tokens are used to encrypt traffic between the client and the server (MIT Kerberos is one of the GSSAPI providers that can be used for that), unlike SSL/TLS, where SSL certificate is used for the same purpose. You can use the `GssEncryptionMode` connection string parameter to control whether GSS session encryption is used; the default is `Prefer`, which will enable the feature if possible but proceed if it's not available. To learn more, see PostgreSQL [docs](https://www.postgresql.org/docs/current/gssapi-enc.html).
+
+## Support for RequireAuth in connection string
+
+`RequireAuth` is used to determine which authentication methods are allowed/required. For example, if you want to make sure that passwords aren't sent as cleartext or MD5, you can specify `RequireAuth=!Password,!MD5`. Or, if you want to make sure to always authenticate either via ScramSHA256 or GSS, then you can specify it as `RequireAuth=ScramSHA256,GSS`. To learn more, see PostgreSQL [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-REQUIRE-AUTH).
+
+## Various other changes
+
+* OpenTelemetry tracing now also included by default for whenever a physical connection to database is open.
+* Added support for `PGAPPNAME` environment variable. It's mapped to `ApplicationName` field of the connection string.
+* Added support for SHA3 hash algorithms with SASL authentication. Previously, Npgsql falled back to SCRAM-SHA-256 if the certificate, provided by the database, had SHA3 signature algorithm.
+* `NpgsqlConnection.Open` now wraps `SocketException` with `NpgsqlException` when hostname can't be resolved.
+* The connection string now supports specifying `TargetSessionAttributes` when used with `NpgsqlDataSourceBuilder`. This means that code creating `NpgsqlDataSource` doesn't have to be aware that it's used with multiple hosts.
 
 ## Breaking changes
 
-* The PostgreSQL `date` and `time` types are now read as .NET [`DateOnly`](https://learn.microsoft.com/dotnet/api/system.dateonly) and [`TimeOnly`](https://learn.microsoft.com/dotnet/api/system.timeonly), instead of [`DateTime`](https://learn.microsoft.com/dotnet/api/system.datetime) and [`TimeSpan`](https://learn.microsoft.com/dotnet/api/system.timespan), respectively. This affects non-generic read methods which return `object`, such as <xref:Npgsql.NpgsqlCommand.ExecuteScalarAsync*> and <xref:Npgsql.NpgsqlDataReader.GetValue*?displayProperty=nameWithType>; you can still read `DateTime` and `TimeSpan` via the generic <xref:Npgsql.NpgsqlDataReader.GetFieldValue%2A>.
+### .NET 6 is no longer supported
+
+With .NET 6 being out of support since November 2024, Npgsql 10.0 also drops support for .NET 6. This change allows us to have a much better capability parity between different versions of .NET, while also removing hundreds lines of compatibility-only code and simplifying the codebase.
+
+### `date` and `time` are now mapped to `DateOnly` and `TimeOnly`
+
+The PostgreSQL `date` and `time` types are now read as .NET [`DateOnly`](https://learn.microsoft.com/dotnet/api/system.dateonly) and [`TimeOnly`](https://learn.microsoft.com/dotnet/api/system.timeonly), instead of [`DateTime`](https://learn.microsoft.com/dotnet/api/system.datetime) and [`TimeSpan`](https://learn.microsoft.com/dotnet/api/system.timespan) by default, respectively. This affects non-generic read methods which return `object`, such as <xref:Npgsql.NpgsqlCommand.ExecuteScalarAsync*> and <xref:Npgsql.NpgsqlDataReader.GetValue*?displayProperty=nameWithType>; you can still read `DateTime` and `TimeSpan` via the generic <xref:Npgsql.NpgsqlDataReader.GetFieldValue%2A>.
+
+### `cidr` is now mapped to `IPNetwork`
+
+With .NET 6 no longer supported by Npgsql, the PostgreSQL `cidr` type is now mapped to `IPNetwork` by default instead of `NpgsqlCidr`. In addition, `NpgsqlCidr` is now obsolete and will be removed in the future.
+
+### Only root CA certificate is used to validate TLS chain
+
+While establishing TLS connection with PostgreSQL, Npgsql will now only use the provided root CA certificate to validate TLS chain instead of using it in addition to the system CA store. This behaviour aligns with libpq and prevents establishing unintended connections.
+
+### COPY operation's `Timeout` property now treats `Timeout.InfiniteTimeSpan` as an infinite timeout instead of `TimeSpan.Zero`
+
+This is in line with other .NET API (like `NetworkStream.ReadTimeout`), where `Timeout.InfiniteTimeSpan` and `Timeout.Infinite` are treated as infinite.
+
+### `PostgresException.BatchCommand` is `null` by default
+
+This prevents accidental leak of queries and parameters when exceptions are logged. To change this behavior you can set `IncludeFailedBatchedCommand` in connection string to `true`.