Add release notes for Npgsql 9 (#370)

conceptual/Npgsql/connection-string-parameters.md

@@ -26,6 +26,7 @@ SSL Key                      | Location of a client key for a client certificate
 SSL Password                 | Password for a key for a client certificate.                                                                                                |
 Root Certificate             | Location of a CA certificate used to validate the server certificate.                                                                       | PGSSLROOTCERT
 Check Certificate Revocation | Whether to check the certificate revocation list during authentication.                                                                     | false
+SSL Negotiation              | Controls how SSL encryption is negotiated with the server, if SSL is used. Introduced in 9.0. [See docs for possible values and more info](security.md). | PGSSLNEGOTIATION
 Channel Binding              | Control whether channel binding is used when authenticating with SASL. Introduced in 8.0.                                                   | Prefer
 Persist Security Info        | Gets or sets a Boolean value that indicates if security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open state. | false
 Kerberos Service Name        | The Kerberos service name to be used for authentication. [See docs for more info](security.md).                                             | postgres
@@ -42,7 +43,7 @@ Minimum Pool Size           | The minimum connection pool size.          | 0
 Maximum Pool Size           | The maximum connection pool size.          | 100 since 3.1, 20 previously
 Connection Idle Lifetime    | The time (in seconds) to wait before closing idle connections in the pool if the count of all connections exceeds `Minimum Pool Size`. Introduced in 3.1. | 300
 Connection Pruning Interval | How many seconds the pool waits before attempting to prune idle connections that are beyond idle lifetime (see `Connection Idle Lifetime`). Introduced in 3.1. | 10
-Connection Lifetime         | The total maximum lifetime of connections (in seconds). Connections which have exceeded this value will be destroyed instead of returned from the pool. This is useful in clustered configurations to force load balancing between a running server and a server just brought online. | 0 (disabled)
+Connection Lifetime         | The total maximum lifetime of connections (in seconds). Connections which have exceeded this value will be destroyed instead of returned from the pool. This is useful in clustered configurations to force load balancing between a running server and a server just brought online. | 3600 (1 hour), in Npgsql 8.0 and before - 0 (disabled)
 
 ## Timeouts and keepalive
 
@@ -126,3 +127,4 @@ PGSSLROOTCERT        | Behaves the same as the [sslrootcert](https://www.postgre
 PGCLIENTENCODING     | Behaves the same as the [client_encoding](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-CLIENT-ENCODING) connection parameter.
 PGTZ                 | Sets the default time zone. (Equivalent to SET timezone TO ....)
 PGOPTIONS            | Behaves the same as the [options](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-OPTIONS) connection parameter.
+PGSSLNEGOTIATION     | Behaves the same as the [sslnegotiation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLNEGOTIATION) connection parameter.

conceptual/Npgsql/release-notes/9.0.md

@@ -1,3 +1,52 @@
 # Npgsql 9.0 Release Notes
 
-Nothing here yet
+Npgsql version 9.0 will be released together with .NET 9 and will be available on nuget. The full list of issues for this release is [available here](https://github.com/npgsql/npgsql/milestone/109?closed=1).
+
+> [!NOTE]
+> We're considering to start dropping support for synchronous API (`NpgsqlConnection.Open`, `NpgsqlCommand.ExecuteNonQuery`, etc) starting with Npgsql 10.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 10.0, while completely removing it for Npgsql 11.0. This is in line with ASP.NET Core and .NET runtime 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).
+
+## Add support for interval's infinity values via NodaTime's Period.MinValue/Period.MaxValue
+
+PostgreSQL 17 added support for infinity values with `interval` type. In turn, Npgsql 9.0 adds native support to read and write them via NodaTime's `Period.MinValue` and `Period.MaxValue`. Note that while using this feature with previous versions of PostgreSQL, instead of infinity values you'll get the minimum and maximum values for `interval` type due to the way infinity values are implemented by PostgreSQL. See [this](https://github.com/npgsql/npgsql/issues/5696) issue for more info.
+
+## Add support for cidr <-> IPNetwork mapping
+
+.NET 8 added a new type [IPNetwork](https://learn.microsoft.com/en-us/dotnet/api/system.net.ipnetwork?view=net-8.0) which represents an IP network with an [IPAddress](https://learn.microsoft.com/en-us/dotnet/api/system.net.ipaddress?view=net-8.0) containing the network prefix and an `int` defining the prefix length. This type seems to be a perfect fit for PostgreSQL's `cidr` type, which is why we added support to read and write it. The default when reading a `cidr` is still NpgsqlCidr in 9.0, though this will likely change in Npgsql 10.0. See [this](https://github.com/npgsql/npgsql/issues/5821) issue for more info.
+
+## Add support for direct SSL
+
+PostgreSQL 17 added support for direct SSL. Direct SSL allows clients to skip sending an SSL support request, which saves a roundtrip while opening a physical connection. This behavior is disabled by default (as it's not supported with previous versions of PostgreSQL), but you can enable it via `SslNegotiation` property in connection string or environment variable `PGSSLNEGOTIATION`. See [this](https://github.com/npgsql/npgsql/issues/5677) issue for more info.
+
+## Add support to modify SslClientAuthenticationOptions
+
+Npgsql 9.0 has a new callback `NpgsqlDataSourceBuilder.UseSslClientAuthenticationOptionsCallback` which is called while connecting to PostgreSQL via `SslStream`. This allows users to modify [SslClientAuthenticationOptions](https://learn.microsoft.com/en-us/dotnet/api/system.net.security.sslclientauthenticationoptions?view=net-8.0), for example changing the supported TLS ciphers. See [this](https://github.com/npgsql/npgsql/issues/5478) issue for more info.
+
+## Add support to modify NegotiateAuthenticationClientOptions
+
+Npgsql 9.0 has a new callback `NpgsqlDataSourceBuilder.NegotiateOptionsCallback` which is called while performing GSSAPI authentication (such as Kerberos). This allows users to modify [NegotiateAuthenticationClientOptions](https://learn.microsoft.com/en-us/dotnet/api/system.net.security.negotiateauthenticationclientoptions?view=net-8.0), for example changing `Credential` property to implement password-based Kerberos authentication. See [this](https://github.com/npgsql/npgsql/issues/5181) issue for more info.
+
+### Add support for parallel in-progress transactions with logical streaming replication protocol V4
+
+This change allows clients to handle multiple in-progress transactions in parallel instead of sequentially. See [this](https://github.com/npgsql/npgsql/issues/5760) issue for more info.
+
+### Add GetFieldName method to ReplicationValue class
+
+This change allows clients to receive the name of changed column while reading rows from replication stream. See [this](https://github.com/npgsql/npgsql/issues/5718) issue for more info.
+
+## Breaking changes
+
+### .NET Standard 2.0 (and .NET Framework) is not supported
+
+Npgsql 9.0 drops support for .NET Standard 2.0, and in turn .NET Framework. Npgsql is a constantly evolving driver, which makes it problematic to add new features which use APIs that do not exist on older versions of .NET. This doesn't mean you can't use Npgsql with .NET Standard 2.0: we're still committed to supporting Npgsql 8.0 (which does support .NET Standard 2.0). See [this](https://github.com/npgsql/npgsql/issues/5296) issue for more info.
+
+### Change some PgOutputReplicationOptions properties to support logical streaming replication protocol V4
+
+The main changes are in the `PgOutputReplicationOptions` class, where `ProtocolVersion` and `StreamingMode` properties were changed to an enum. See [this](https://github.com/npgsql/npgsql/issues/5760) issue for more info.
+
+### Multiple ssl related callbacks on NpgsqlDataSourceBuilder are deprecated in favor of UseSslClientAuthenticationOptionsCallback
+
+With the new `UseSslClientAuthenticationOptionsCallback` callback, users have much more control over the way Npgsql connects to PostgreSQL via `SslStream`. This makes other callbacks, like `UseUserCertificateValidationCallback` and `UseClientCertificate` less useful, which is why we're obsoleting them. See [this](https://github.com/npgsql/npgsql/issues/5478) issue for more info.
+
+### The default value of ConnectionLifetime property in connection string is set to 1 hour
+
+Previously, the default value of this property was set to 0, which made connections last indefinitely. The old behavior was problematic because each physical connection on PostgreSQL's side has holds on certain caches, which can only grow over time. See [this](https://github.com/npgsql/npgsql/pull/5662) pull request for more info.

conceptual/Npgsql/security.md

@@ -74,6 +74,14 @@ To disable certificate validation when using `Require`, set `Trust Server Certif
 
 ---
 
+### SSL Negotiation
+
+Starting with Npgsql 9.0, you can control how SSL encryption is negotiated while connecting to PostgreSQL via the `SSL Negotiation` connection string parameter, or via the `PGSSLNEGOTIATION` environment variable. In the default `postgres` mode, the client first asks the server if SSL is supported. In `direct` mode, the client starts the standard SSL handshake directly after establishing the TCP/IP connection.
+
+Enabling this option (by changing it to `direct` mode) can improve latency while opening a physical connection by removing one round trip.
+
+This option is only supported with PostgreSQL 17 and above.
+
 ### Advanced server certificate validation
 
 If the root CA of the server certificate isn't installed in your machine's CA store, validation will fail. Either install the certificate in your machine's CA store, or point to it via the `Root Certificate` connection string parameter or via the `PGSSLROOTCERT` environment variable.