Some release notes and breaking changes for 8.0 (#306)

conceptual/EFCore.PG/release-notes/8.0.md

@@ -0,0 +1,52 @@
+# 8.0 Release Notes
+
+**The below release notes and breaking changes list aren't yet complete. Check back soon for more notes.**
+
+## New features
+
+New features will be documented later.
+
+## Breaking changes
+
+Note: version 8.0 of the lower-level Npgsql ADO.NET driver, which is used by the EF provider, also has some breaking changes. It's recommended to read the [release notes](../../Npgsql/release-notes/8.0.md) for that as well.
+
+### <a name="dynamic-optin">JSON POCO and other dynamic features now require an explicit opt-in
+
+Because of the NativeAOT and trimming work done for Npgsql 8.0 ([release notes](../../Npgsql/release-notes/8.0.md)), certain features now require an explicit opt-in, which you must add either on your <xref:Npgsql.NpgsqlDataSourceBuilder> or on <xref:Npgsql.NpgsqlConnection.GlobalTypeMapper?displayProperty=nameWithType>:
+
+PostgreSQL type                          | Default .NET type
+---------------------------------------- | --------------------------
+JSON POCO mapping, JsonNode and subtypes | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableDynamicJsonMappings>
+Unmapped enums, ranges, multiranges      | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableUnmappedTypes>
+Read PostgreSQL records as .NET tuples   | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableRecordsAsTuples>
+
+Existing code using the above features will start throwing exceptions after upgrading to version 8.0 of the EF Core provider; the exceptions provide explicit guidance on how to add the opt-ins.
+
+Note that EF Core itself is not yet compatible with NativeAOT, and Npgsql can only be used in NativeAOT applications without EF Core.
+
+### Obsoleted HasPostgresArrayConversion
+
+With EF 8.0 introducing first-class support for [primitive collections](https://devblogs.microsoft.com/dotnet/announcing-ef8-preview-4), the PostgreSQL driver aligned its PostgreSQL array support to use that. As a result, `HasPostgresArrayConversion` can no longer be used to configure value-converted arrays; instead, the new standard EF mechanism can be used.
+
+For example, the following Npgsql-specific code would configure value conversion for a property of type `MyType[]` to a PostgreSQL array of strings in EF Core 6 or 7:
+
+```c#
+modelBuilder.Entity<Blog>().Property(b => b.ValueConvertedArray)
+    .HasPostgresArrayConversion(x => x.ToString(), s => MyType.Parse(s));
+```
+
+The same can now achieved with the following standard EF 8 code:
+
+```c#
+modelBuilder.Entity<Blog>().PrimitiveCollection(b => b.ValueConvertedArray)
+    .ElementType()
+    .HasConversion(typeof(MyConverter));
+
+class MyConverter : ValueConverter<MyType, string>
+{
+    public MyConverter()
+        : base(x => x.ToString(), s => MyType.Parse(s))
+    {
+    }
+}
+```

conceptual/EFCore.PG/toc.yml

@@ -2,16 +2,18 @@
   href: index.md
 - name: Release notes
   items:
+  - name: "8.0"
+    href: release-notes/8.0.md
   - name: "7.0"
     href: release-notes/7.0.md
   - name: "6.0"
     href: release-notes/6.0.md
-  - name: "3.1"
-    href: release-notes/3.1.md
   - name: Out of support
     items:
     - name: "5.0"
       href: release-notes/5.0.md
+    - name: "3.1"
+      href: release-notes/3.1.md
     - name: "2.2"
       href: release-notes/2.2.md
     - name: "2.1"

conceptual/Npgsql/basic-usage.md

@@ -29,6 +29,9 @@ await using var dataSource = dataSourceBuilder.Build();
 
 You typically build a single data source, and then use that instance throughout your application; data sources are thread-safe, and (usually) correspond to a connection pool inside Npgsql. For more information on data source configuration, consult the relevant documentation pages.
 
+> [!NOTE]
+> If you're using NativeAOT and trimming and are concerned with minimizing application size, consider using <xref:Npgsql.NpgsqlSlimDataSourceBuilder>; this builder includes only the very minimum of functionality by default, and allows adding additional features via opt-ins.
+
 ## Basic SQL Execution
 
 Once you have a data source, an <xref:Npgsql.NpgsqlCommand> can be used to execute SQL against it:

conceptual/Npgsql/compatibility.md

@@ -12,12 +12,29 @@ Earlier versions may still work but we don't perform continuous testing on them
 Npgsql is an ADO.NET-compatible provider, so it has the same APIs as other .NET database drivers and should behave the same.
 Please let us know if you notice any non-standard behavior.
 
+## NativeAOT and trimming
+
+NativeAOT allows using ahead-of-time compilation to publish a fully self-contained application that has been compiled to native code. Native AOT apps have faster startup time and smaller memory footprints, and thanks to trimming can also have a much smaller size footprint on disk.
+
+Starting with version 8.0, Npgsql is fully compatible with NativeAOT and trimming. The majority of features are compatible with NativeAOT/trimming and can be used without issues, and most applications using Npgsql can be used as-is with NativeAOT/trimming without any changes. A few features which are incompatible require an explicit code opt-in, which generates a warning if used with NativeAOT/trimming enabled.
+
 ## .NET Framework/.NET Core/mono
 
 Npgsql 4.* targets .NET Framework 4.6.1, as well as [.NET Standard 2.0](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) which allows it to run on .NET Core. It is also tested and runs well on mono.
 
 Npgsql 5.* targets .NET Standard 2.0 and .NET 5. Starting with this version, we no longer run regression tests on .NET Framework and mono. In addition, the Visual Studio extension (VSIX) and the MSI GAC installer have been discontinued.
 
+## pgbouncer
+
+Npgsql works well with PgBouncer, but there are some quirks to be aware of.
+
+* In many cases, you'll want to turn off Npgsql's internal connection pool by specifying `Pooling=false` on the connection string.
+* If you decide to keep Npgsql pooling on along with PgBouncer, and are using PgBouncer's transaction or statement mode, then you  need to specify `No Reset On Close=true` on the connection string. This disables Npgsql's connection reset logic (`DISCARD ALL`), which gets executed when a connection is returned to Npgsql's pool, and which makes no sense in these modes.
+* Prior to version 3.1, Npgsql sends the `statement_timeout` startup parameter when it connects, but this parameter isn't supported by pgbouncer.
+  You can get around this by specifying `CommandTimeout=0` on the connection string, and then manually setting the `CommandTimeout`
+  property on your `NpgsqlCommand` objects. Version 3.1 no longer sends `statement_timeout`.
+* PgBouncer below 1.12 doesn't support SASL authentication.
+
 ## Amazon Redshift
 
 Amazon Redshift is a cloud-based data warehouse originally based on PostgreSQL 8.0.2.
@@ -37,14 +54,3 @@ Additional known issues:
 ## DigitalOcean Managed Database
 
 DigitalOcean's Managed Database services requires you to connect to PostgreSQL over SSL.  Unfortunately when you enable it in your connection string, you will get the same error regarding `ssl_renegotiation_limit` as Amazon Redshift.  The Redshift compatibility mode setting resolves the issue on DigitalOcean.
-
-## pgbouncer
-
-Npgsql works well with PgBouncer, but there are some quirks to be aware of.
-
-* In many cases, you'll want to turn off Npgsql's internal connection pool by specifying `Pooling=false` on the connection string.
-* If you decide to keep Npgsql pooling on along with PgBouncer, and are using PgBouncer's transaction or statement mode, then you  need to specify `No Reset On Close=true` on the connection string. This disables Npgsql's connection reset logic (`DISCARD ALL`), which gets executed when a connection is returned to Npgsql's pool, and which makes no sense in these modes.
-* Prior to version 3.1, Npgsql sends the `statement_timeout` startup parameter when it connects, but this parameter isn't supported by pgbouncer.
-  You can get around this by specifying `CommandTimeout=0` on the connection string, and then manually setting the `CommandTimeout`
-  property on your `NpgsqlCommand` objects. Version 3.1 no longer sends `statement_timeout`.
-* PgBouncer below 1.12 doesn't support SASL authentication.

conceptual/Npgsql/release-notes/8.0.md

@@ -1,29 +1,36 @@
 # Npgsql 8.0 Release Notes
 
-Npgsql version 8.0 is under development, and is available as preview versions.
+**The below release notes and breaking changes list aren't yet complete. Check back soon for more notes.**
+
+Npgsql version 8.0 is under development, and is available as release candidate versions.
 
 ## New features
 
-## Breaking changes
+### NativeAOT and trimming support
+
+Npgsql 8.0 now has 1st-class support for NativeAOT and trimming; the entire library has been properly annotated and is safe for use in applications. The majority of features have been made compatible with NativeAOT/trimming and can be used without issues, and most applications using Npgsql can be used as-is with NativeAOT/trimming without any changes. A few features which are incompatible require an explicit code opt-in, which generates a warning if used with NativeAOT/trimming enabled ([see breaking change note](#dynamic-optin)).
 
-### System.Text.Json mapping support must now be opted into
+Considerable effort has gone into reducing Npgsql's size footprint; a minimal Npgsql application using NativeAOT and trimming now takes only around 5MB of disk space. To allow users to achieve a minimal size footprint, <xref:Npgsql.NpgsqlSlimDataSourceBuilder> has been introduced; unlike the standard <xref:Npgsql.NpgsqlDataSourceBuilder>, this builder includes only the very minimum of functionality by default, and allows adding additional features via opt-ins. This allows a pay-per-play approach to application size, where developers can choose only the features they actually need for optimal size. For more information on <xref:Npgsql.NpgsqlDataSourceBuilder>
+
+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).
+
+## Breaking changes
 
-In previous versions, transparent JSON serialization and deserialization was supported via System.Text.Json. That support hasn't changed, but you must now explicitly opt into it. If you're using `NpgsqlDataSource`, simply add the following when building your data source:
+### <a name="dynamic-optin">JSON POCO and other dynamic features now require an explicit opt-in
 
-```c#
-var builder = new NpgsqlDataSourceBuilder("<connection string>");
-builder.UseSystemTextJson();
-await using var dataSource = builder.Build();
-```
+Npgsql 8.0 is fully compatible with NativeAOT and trimming (see above). While most driver capabilities have been made to work in those profiles, certain features involve dynamic coding practices and are incompatible with NativeAOT and/or trimming - at least for now. As a result, these features now require explicit opt-ins (annotated to be incompatible with NativeAOT/trimming), which you must add either on your <xref:Npgsql.NpgsqlDataSourceBuilder> or on <xref:Npgsql.NpgsqlConnection.GlobalTypeMapper?displayProperty=nameWithType>:
 
-Or, if you're using the legacy global type mapper, add the following at the start of your application, before any Npgsql operations are performed:
+PostgreSQL type                          | Default .NET type
+---------------------------------------- | --------------------------
+JSON POCO mapping, JsonNode and subtypes | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableDynamicJsonMappings>
+Unmapped enums, ranges, multiranges      | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableUnmappedTypes>
+Read PostgreSQL records as .NET tuples   | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableRecordsAsTuples>
 
-```c#
-NpgsqlConnection.GlobalTypeMapper.UseSystemTextJson();
-```
+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.
 
-This change was done for several reasons. For one, as part of a push to improve the trimmability of Npgsql (for smaller sizes), the opt in ensures that System.Text.Json is only brought in for applications which use it, and gets trimmed out otherwise. In addition, the new opt-in API allows specifying configuration options, such as [JsonSerializerOptions](https://learn.microsoft.com/dotnet/api/system.text.json.jsonserializeroptions); this wasn't previously possible.
+### Plugin APIs have been changed for NativeAOT/trimming support
 
-## Contributors
+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.
 
-Thank you very much to the following people who have contributed to the individual 8.0.x. releases.
+> [!WARNING]
+> If you're a plugin developer, be aware that some last API changes may still be done; it's advisable to wait until 8.0 is released before adapting your plugin. In any case, please reach out to us via Github issues if you encounter any issues or require guidance!

conceptual/Npgsql/toc.yml

@@ -2,22 +2,26 @@
   href: index.md
 - name: Release notes
   items:
+  - name: "8.0"
+    href: release-notes/8.0.md
   - name: "7.0"
     href: release-notes/7.0.md
   - name: "6.0"
     href: release-notes/6.0.md
-  - name: "5.0"
-    href: release-notes/5.0.md
-  - name: "4.1"
-    href: release-notes/4.1.md
-  - name: "4.0"
-    href: release-notes/4.0.md
-  - name: "3.2"
-    href: release-notes/3.2.md
-  - name: "3.1"
-    href: release-notes/3.1.md
-  - name: "3.0"
-    href: release-notes/3.0.md
+  - name: Out of support
+    items:
+    - name: "5.0"
+      href: release-notes/5.0.md
+    - name: "4.1"
+      href: release-notes/4.1.md
+    - name: "4.0"
+      href: release-notes/4.0.md
+    - name: "3.2"
+      href: release-notes/3.2.md
+    - name: "3.1"
+      href: release-notes/3.1.md
+    - name: "3.0"
+      href: release-notes/3.0.md
 - name: Installation
   href: installation.md
 - name: Basic usage