Npgsql 5.0 Release Notes
Npgsql 5.0 is out and available at nuget.org.
The full list of issues for this release is available here.
PostgreSQL logical and physical replication
PostgreSQL replication creating programs which receive a continuous, live stream of all updates happening in a PostgreSQL database or set of tables. It can be used for auditing purposes, continuously exporting certain (or all) changes to another database or format, or various other purposes. See the documentation for more details.
This major feature was developed by @Brar, many thanks!
Improved support for cancellation and timeout
When the user requests cancellation (via a cancellation token or NpgsqlCommand.Cancel()), or when the Command Timeout expires, Npgsql now takes the following steps:
- Contact PostgreSQL and attempt to cancel the running command. If successful, PostgreSQL immediately stops processing the command and is free to do other work. In previous versions, queries were sometimes left running on the server.
- If PostgreSQL cancellation isn't successful within a short time window, the network is likely down. Npgsql forcibly closes the physical connection and raises an exception, making sure the application isn't blocked.
Previous support was inconsistent across cancellation and timeout, and async I/O was only partially supported.
Thanks to @vonzshik for all their valuable work on this!
Multiplexing is an experimental new way for the driver to handle commands and connections: user code no longer receives an exclusive physical connection from Npgsql's internal pool, but rather submits commands to be executed on any available connection. This is a much more efficient use of connections, which can lead to:
- Significant reduction to the number of required PostgreSQL physical connection requirements, and removing load from the server.
- Continued uptime even when the maximum allowed connection count has been reached.
- A potentially substantial performance boost on the TechEmpower benchmark (next round to be published).
Multiplexing is disabled by default, is considered experimental and must be explicitly opted into. Full documentation will be available soon.
All Npgsql APIs are now fully annotated for C# nullable references (#3120), in line with the new annotations in System.Data released in .NET 5.0.
Support for arrays of nullable value types
It is now possible to read PostgreSQL arrays as CLR arrays of nullable value types. For example, a PostgreSQL
integer column can now be read as follows:
var array = reader.GetFieldValue<int?>(0);
Previously, only non-nullable value arrays were supported, and nulls were translated to the default value (e.g. 0).
Thanks to @Brar for developing this feature.
Close connections past a certain age
Connection Lifetime connection string parameter can now be used to unconditionally close connections which have reached a certain age. Once such a connection is returned to the pool, it is destroyed and a new connection will be created if needed. This is useful in clustered configurations to force load balancing between a running server and a server just brought online, or to mitigate certain resource leaks.
Thanks to @FlorianRainer for collaborating on this feature.
- Npgsql no longer targets .NET Framework 4.6.1. Since .NET Standard 2.0 is targeted, it is still possible to use Npgsql from .NET Framework applications; however, we no longer run regression tests on .NET Framework and will only fix bugs on a best-effort basis. In addition, the Visual Studio extension (VSIX) and the MSI GAC installer have been discontinued. #3269.
- Npgsql targets the
netcoreapp3.1TFM instead of
netcoreapp3.0, which is out of support (#3160).
- When command timeout occurs, Npgsql now raises an NpgsqlException wrapping a TimeoutException (#3132). Previously, an NpgsqlException wrapping an IOException was raised.
- Similarly, when cancellation occurs, Npgsql now raises an OperationCanceledException when a command is cancelled (both via an async cancellation token, and via NpgsqlCommand.Cancel()). Previously, NpgsqlCommand.Cancel caused a PostgresException to be raised instead.
- When reading PostgreSQL arrays, if a null value is being read into a CLR arrays of a non-nullable value type, an exception is now thrown (#443). Previously, the default value was populated instead. It is now possible to read arrays of nullable value types instead.
NpgsqlTransaction.IsCompletedproperty has been removed. The application must itself track when a transaction is committed or rolled back.
- Support for unmapped PostgreSQL composite types has been removed (#2403).
- The ordering in which Npgsql checks alternative password sources has changed (#2695, #2657). This only affects applications which omit the password from the connection string.
- If the connection string specifies a PGPASS file, Npgsql now throws if that file doesn't exist (#2694).
- The TcpKeepAliveTime and TcpKeepAliveInterval connection string parameters are now expressed in seconds instead of milliseconds (#1936).
- The NpgsqlConnection.GetSchema() API now returns all indexes in the database (2958). Previously, only indexes in the
- NpgsqlOperationInProgressException now inherits from NpgsqlException.
- NpgsqlBinaryImporter.Complete() has been changed to return a
ulongreporting the number of imported rows (#2112).
- The Npgsql.RawPostgis plugin has been discontinued (#3201). Npgsql now allows any field to be read as raw binary data, so the plugin is no longer necessary.
- ~Support for non-standard-conforming strings has been dropped (#2931).~ Support for non-standard-confirming strings has been restored in 5.0.1 (except for multiplexing).
- Npgsql no longer supports SASL authentication with PgBouncer below 1.12.
Thank you very much to the following people who have contributed to the individual 5.0.x. releases.