From 96ea418b0bbdccbd4132218c43c2ffd453e38259 Mon Sep 17 00:00:00 2001 From: Nikita Kazmin Date: Mon, 21 Oct 2024 15:50:13 +0300 Subject: [PATCH 1/4] Add release notes for Npgsql 9 --- conceptual/Npgsql/release-notes/9.0.md | 51 +++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/conceptual/Npgsql/release-notes/9.0.md b/conceptual/Npgsql/release-notes/9.0.md index f1b94515..ad2c9843 100644 --- a/conceptual/Npgsql/release-notes/9.0.md +++ b/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 moves 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. 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 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 + +Starting with Npgsql 9.0 we're dropping 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 (like `NegotiateOptionsCallback` which allows to change [NegotiateAuthenticationClientOptions](https://learn.microsoft.com/en-us/dotnet/api/system.net.security.negotiateauthenticationclientoptions?view=net-8.0)) which use API that does not exist on older versions of .NET. This doesn't mean you can't use Npgsql with .NET Standard 2.0 as we're still commited to support Npgsql 8.0 (which does support .NET Standard 2.0) up until .NET 8 is out of support. 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 `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 a new callback `UseSslClientAuthenticationOptionsCallback` users have much more control over the way Npgsql connects to PostgreSQL via `SslStream`. This makes other callbacks, like `UseUserCertificateValidationCallback` and `UseClientCertificate`, offer subpar experience, which is why we deprecate 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 to 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. From bd70e3a0b27a195e2173d407e4b0d10def2b009e Mon Sep 17 00:00:00 2001 From: Nikita Kazmin Date: Mon, 21 Oct 2024 15:51:51 +0300 Subject: [PATCH 2/4] Fix --- conceptual/Npgsql/release-notes/9.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/conceptual/Npgsql/release-notes/9.0.md b/conceptual/Npgsql/release-notes/9.0.md index ad2c9843..098694be 100644 --- a/conceptual/Npgsql/release-notes/9.0.md +++ b/conceptual/Npgsql/release-notes/9.0.md @@ -3,7 +3,7 @@ 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 moves 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). +> 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 move 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 @@ -11,7 +11,7 @@ PostgreSQL 17 added support for infinity values with `interval` type. In turn, N ## 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. See [this](https://github.com/npgsql/npgsql/issues/5821) issue for more info. +.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. See [this](https://github.com/npgsql/npgsql/issues/5821) issue for more info. ## Add support for direct SSL From 9998a8698ded97356136fcba01f9a222cf604e7c Mon Sep 17 00:00:00 2001 From: Nikita Kazmin Date: Tue, 22 Oct 2024 12:31:16 +0300 Subject: [PATCH 3/4] Update connection-string-parameters and security pages --- conceptual/Npgsql/connection-string-parameters.md | 4 +++- conceptual/Npgsql/security.md | 8 ++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/conceptual/Npgsql/connection-string-parameters.md b/conceptual/Npgsql/connection-string-parameters.md index cc32dc06..9779a40c 100644 --- a/conceptual/Npgsql/connection-string-parameters.md +++ b/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. diff --git a/conceptual/Npgsql/security.md b/conceptual/Npgsql/security.md index 6d21c998..f97d470e 100644 --- a/conceptual/Npgsql/security.md +++ b/conceptual/Npgsql/security.md @@ -74,6 +74,14 @@ To disable certificate validation when using `Require`, set `Trust Server Certif --- +### SSL Negotiation + +Starting Npgsql 9.0 you 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. From bb248783745130b8efbab868322fae1ad9122925 Mon Sep 17 00:00:00 2001 From: Nikita Kazmin Date: Tue, 22 Oct 2024 12:32:17 +0300 Subject: [PATCH 4/4] Space --- conceptual/Npgsql/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conceptual/Npgsql/security.md b/conceptual/Npgsql/security.md index f97d470e..d06e62ed 100644 --- a/conceptual/Npgsql/security.md +++ b/conceptual/Npgsql/security.md @@ -80,7 +80,7 @@ Starting Npgsql 9.0 you control how SSL encryption is negotiated while connectin 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. +This option is only supported with PostgreSQL 17 and above. ### Advanced server certificate validation