Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document networking mapping changes #307

Merged
merged 2 commits into from
Oct 11, 2023
Merged

Document networking mapping changes #307

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5f27081
Document networking mapping changes
roji Oct 11, 2023
19a4ef0
Merge branch 'main' into Networking
roji Oct 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions conceptual/EFCore.PG/mapping/translations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,9 @@ ValueTuple.Create(a, b).Equals(ValueTuple.Create(c, d))

## Network functions

> [!NOTE]
> As of Npgsql 8.0, `IPAddress` and `NpgsqlCidr` are implicitly convertible to `NpgsqlInet`, and so can be used with the functions below which accept `inet`.

.NET | SQL
------------------------------------------------ | ---
IPAddress.Parse(string) | [CAST(string AS inet)](https://www.postgresql.org/docs/current/datatype-net-types.html#DATATYPE-INET)
Expand All @@ -193,6 +196,7 @@ EF.Functions.Add(inet, int) | [inet + int](https://www.post
EF.Functions.Subtract(inet, int) | [inet - int](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-OPERATORS-TABLE)
EF.Functions.Subtract(inet1, inet2) | [inet1 - inet2](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-OPERATORS-TABLE)
EF.Functions.Abbreviate(inet) | [abbrev(inet)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.Abbreviate(cidr) | [abbrev(cidr)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.Broadcast(inet) | [broadcast(inet)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.Family(inet) | [family(inet)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.Host(inet) | [host(inet)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
Expand All @@ -201,6 +205,7 @@ EF.Functions.MaskLength(inet) | [masklen(inet)](https://www.p
EF.Functions.Netmask(inet) | [netmask(inet)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.Network(inet) | [network(inet)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.SetMaskLength(inet) | [set_masklen(inet)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.SetMaskLength(cidr) | [set_masklen(cidr)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.Text(inet) | [text(inet)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.SameFamily(inet1, inet2) | [inet_same_family(inet1, inet2)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
EF.Functions.Merge(inet1, inet2) | [inet_merge(inet1, inet2)](https://www.postgresql.org/docs/current/functions-net.html#CIDR-INET-FUNCTIONS-TABLE)
Expand Down
14 changes: 14 additions & 0 deletions conceptual/Npgsql/release-notes/8.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

Npgsql version 8.0 is under development, and is available as release candidate versions.

> [!NOTE]
> Npgsql 8.0 will be the last version to support .NET Framework (via .NET Standard 2.0). Starting with 9.0, Npgsql will only target .NET TFMs supported at release time (i.e. `net6.0`).

## New features

### NativeAOT and trimming support
Expand All @@ -14,6 +17,13 @@ Considerable effort has gone into reducing Npgsql's size footprint; a minimal Np

Making Npgsql NativeAOT/trimming-compatible was a far-reaching effort, affecting many parts of the driver and involving a rewrite of large parts of Npgsql's internals (leading to many other internal improvements). This huge task was done mainly by [Nino Floris](http://github.com/ninofloris), with considerable contributions by [Nikita Kazmin](https://github.com/vonzshik).

### Improvements to networking type mapping

The mappings for the PostgreSQL networking types `inet` and `cidr` have been cleaned up and rationalized:

* In addition to .NET <xref:System.Net.IPAddress>, PostgreSQL `inet` can also mapped to be mapped to <xref:NpgsqlTypes.NpgsqlInet>, which is an immutable struct containing both IP and netmask components.
* PostgreSQL `cidr` is now mapped to the newly-introduced <xref:NpgsqlTypes.NpgsqlCidr>. The mapping to `ValueTuple<IPAddress, int>` has been removed.

## Breaking changes

### <a name="dynamic-optin">JSON POCO and other dynamic features now require an explicit opt-in
Expand All @@ -28,6 +38,10 @@ Read PostgreSQL records as .NET tuples | <xref:Npgsql.INpgsqlTypeMapperExtensi

Existing code using the above features will start throwing exceptions after upgrading to Npgsql 8.0; the exceptions provide explicit guidance on how to add the opt-ins.

### `cidr` now maps to `NpgsqlCidr` instead of `ValueTuple<IPAddress, int>`

As part of improving Npgsql's support for the PostgreSQL network mappings (see above), the PostgreSQL `cidr` type now maps to the newly-introduced <xref:NpgsqlTypes.NpgsqlCidr>, and can no longer be mapped to `ValueTuple<IPAddress, int>`.

### Plugin APIs have been changed for NativeAOT/trimming support

As part of the effort to make Npgsql compatible with NativeAOT and trimming, the plugin API was changed in fundamental, breaking ways. Although this API never had the stability guarantees of a true public API (it was and still is in an Internal namespace), external plugins which were developed with it will require adjustments.
Expand Down
6 changes: 4 additions & 2 deletions conceptual/Npgsql/types/basic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ date | DateTime | DateOnly (6.0+)
time without time zone | TimeSpan | TimeOnly (6.0+)
time with time zone | DateTimeOffset |
interval | TimeSpan<sup>3</sup> | <xref:NpgsqlTypes.NpgsqlInterval>
cidr | (IPAddress, int) | NpgsqlInet
inet | IPAddress | NpgsqlInet, (IPAddress, int)
cidr | <xref:NpgsqlTypes.NpgsqlCidr><sup>4</sup> |
inet | IPAddress | <xref:NpgsqlTypes.NpgsqlInet>
macaddr | PhysicalAddress |
tsquery | NpgsqlTsQuery |
tsvector | NpgsqlTsVector |
Expand Down Expand Up @@ -73,6 +73,8 @@ array types | Array (of element type) |

<sup>3</sup> PostgreSQL intervals with month or year components cannot be read as TimeSpan. Consider using NodaTime's [Period](https://nodatime.org/3.0.x/api/NodaTime.Period.html) type, or <xref:NpgsqlTypes.NpgsqlInterval>.

<sup>4</sup> Prior to version 8.0, the default mapping for `cidr` was `ValueTuple<IPAddress, int>`.

The Default .NET type column specifies the data type `NpgsqlDataReader.GetValue()` will return.

`NpgsqlDataReader.GetProviderSpecificValue` will return a value of a data type specified in the Provider-specific type column, or the Default .NET type if there is no specialization.
Expand Down