Document networking mapping changes (#307)

npgsql · Oct 11, 2023 · 96743d5 · 96743d5
1 parent f43a166
commit 96743d5
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 2 deletions.
diff --git a/conceptual/EFCore.PG/mapping/translations.md b/conceptual/EFCore.PG/mapping/translations.md
@@ -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)
@@ -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)
@@ -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)

diff --git a/conceptual/Npgsql/release-notes/8.0.md b/conceptual/Npgsql/release-notes/8.0.md
@@ -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
@@ -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
@@ -38,6 +48,10 @@ To prevent existing usage of `Require` to silently stop validating, Npgsql 6.0 a
 
 For more context, see [#3988](https://github.com/npgsql/npgsql/issues/3988#issuecomment-933011009).
 
+### `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.

diff --git a/conceptual/Npgsql/types/basic.md b/conceptual/Npgsql/types/basic.md
@@ -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             |
@@ -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.