Npgsql 5.0 Release Notes

Npgsql 5.0 is out and available at nuget.org.

New features

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!

Issue: #1520

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!

Issue: #3166

Connection multiplexing

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.

Issue: #1982

Nullable references

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.

Issue: #443

Close connections past a certain age

The 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.

Issue: #1810

Breaking changes

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.1 TFM 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.
The NpgsqlTransaction.IsCompleted property 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 search_path were returned.
NpgsqlOperationInProgressException now inherits from NpgsqlException.
NpgsqlBinaryImporter.Complete() has been changed to return a ulong reporting 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.

Contributors

Thank you very much to the following people who have contributed to the individual 5.0.x. releases.

Milestone 5.0.14

Contributor	Assigned issues
@vonzshik	1

Milestone 5.0.11

Contributor	Assigned issues
@vonzshik	4
@aromaa	1
@kislovs	1
@roji	1

Milestone 5.0.10

Contributor	Assigned issues
@vonzshik	11
@roji	5
@Brar	1

Milestone 5.0.7

Contributor	Assigned issues
@vonzshik	8
@roji	4
@Brar	1
@chrisdcmoore	1

Milestone 5.0.5

Contributor	Assigned issues
@vonzshik	6
@roji	3

Milestone 5.0.4

Contributor	Assigned issues
@vonzshik	5
@roji	2
@Brar	1
@neyromant	1
@YohDeadfall	1

Milestone 5.0.3

Contributor	Assigned issues
@baal2000	1
@roji	1
@vonzshik	1

Milestone 5.0.2

Contributor	Assigned issues
@vonzshik	4
@roji	2
@Brar	1
@cime	1
@YohDeadfall	1

Milestone 5.0.1.1

Contributor	Assigned issues
@vonzshik	3
@roji	2
@YohDeadfall	1

Milestone 5.0.0

Contributor	Assigned issues
@roji	34
@vonzshik	19
@YohDeadfall	16
@Brar	7
@warcha	5
@manandre	2
@ch-asimakopoulos	1
@chrisdcmoore	1
@FlorianRainer	1
@NinoFloris	1
@russellfoster	1
@TwentyFourMinutes	1

Table of Contents