From c829a4b6b94bc4d1534e34f9604468e64c9ac2d9 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Sun, 20 Aug 2023 10:27:45 +0200 Subject: [PATCH 1/4] 8.0 breaking change note on HasPostgresArrayConversion obsoletion --- conceptual/EFCore.PG/release-notes/8.0.md | 36 +++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 conceptual/EFCore.PG/release-notes/8.0.md diff --git a/conceptual/EFCore.PG/release-notes/8.0.md b/conceptual/EFCore.PG/release-notes/8.0.md new file mode 100644 index 000000000..da8d7c442 --- /dev/null +++ b/conceptual/EFCore.PG/release-notes/8.0.md @@ -0,0 +1,36 @@ +# 8.0 Release 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. + +### 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().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().PrimitiveCollection(b => b.ValueConvertedArray) + .ElementType() + .HasConversion(typeof(MyConverter)); + +class MyConverter : ValueConverter +{ + public MyConverter() + : base(x => x.ToString(), s => MyType.Parse(s)) + { + } +} +``` From 507f04362c80e809ca382b4a909baa5cb0c5435d Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Tue, 10 Oct 2023 18:10:00 +0200 Subject: [PATCH 2/4] NativeAOT release notes for 8.0 --- conceptual/EFCore.PG/release-notes/8.0.md | 2 ++ conceptual/EFCore.PG/toc.yml | 6 ++-- conceptual/Npgsql/basic-usage.md | 3 ++ conceptual/Npgsql/compatibility.md | 28 +++++++++++------- conceptual/Npgsql/release-notes/8.0.md | 36 +++++++++++++---------- conceptual/Npgsql/toc.yml | 28 ++++++++++-------- 6 files changed, 62 insertions(+), 41 deletions(-) diff --git a/conceptual/EFCore.PG/release-notes/8.0.md b/conceptual/EFCore.PG/release-notes/8.0.md index da8d7c442..dcc1ad770 100644 --- a/conceptual/EFCore.PG/release-notes/8.0.md +++ b/conceptual/EFCore.PG/release-notes/8.0.md @@ -1,5 +1,7 @@ # 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. diff --git a/conceptual/EFCore.PG/toc.yml b/conceptual/EFCore.PG/toc.yml index 5afb0b465..46c8cccbe 100644 --- a/conceptual/EFCore.PG/toc.yml +++ b/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" diff --git a/conceptual/Npgsql/basic-usage.md b/conceptual/Npgsql/basic-usage.md index 4625e0133..46a599c2c 100644 --- a/conceptual/Npgsql/basic-usage.md +++ b/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 ; 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 can be used to execute SQL against it: diff --git a/conceptual/Npgsql/compatibility.md b/conceptual/Npgsql/compatibility.md index befaecd57..31e6204ea 100644 --- a/conceptual/Npgsql/compatibility.md +++ b/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. diff --git a/conceptual/Npgsql/release-notes/8.0.md b/conceptual/Npgsql/release-notes/8.0.md index 10df3e777..ac2de1799 100644 --- a/conceptual/Npgsql/release-notes/8.0.md +++ b/conceptual/Npgsql/release-notes/8.0.md @@ -1,29 +1,33 @@ # 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, has been introduced; unlike the standard , 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 -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: +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 also by [Nikita Kazmin](https://github.com/vonzshik). + +## Breaking changes -```c# -var builder = new NpgsqlDataSourceBuilder(""); -builder.UseSystemTextJson(); -await using var dataSource = builder.Build(); -``` +### JSON POCO and other dynamic features now require an explicit opt-in -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: +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 or on : -```c# -NpgsqlConnection.GlobalTypeMapper.UseSystemTextJson(); -``` +PostgreSQL type | Default .NET type +---------------------------------------- | -------------------------- +JSON POCO mapping, JsonNode and subtypes | +Unmapped enums, ranges, multiranges | +Read PostgreSQL records as .NET tuples | -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. +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. -## Contributors +### Plugin APIs have been changed for NativeAOT/trimming support -Thank you very much to the following people who have contributed to the individual 8.0.x. releases. +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 were developed with it which will require adjustments. diff --git a/conceptual/Npgsql/toc.yml b/conceptual/Npgsql/toc.yml index b854eeff1..ad101a946 100644 --- a/conceptual/Npgsql/toc.yml +++ b/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 From 0b5ce88dc23fe84dc74c9917b412167cb8563e47 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Wed, 11 Oct 2023 14:41:41 +0200 Subject: [PATCH 3/4] Address review comments --- conceptual/Npgsql/release-notes/8.0.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/conceptual/Npgsql/release-notes/8.0.md b/conceptual/Npgsql/release-notes/8.0.md index ac2de1799..0ff8b2f1b 100644 --- a/conceptual/Npgsql/release-notes/8.0.md +++ b/conceptual/Npgsql/release-notes/8.0.md @@ -12,7 +12,7 @@ Npgsql 8.0 now has 1st-class support for NativeAOT and trimming; the entire libr 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, has been introduced; unlike the standard , 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 -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 also by [Nikita Kazmin](https://github.com/vonzshik). +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 @@ -30,4 +30,7 @@ Existing code using the above features will start throwing exceptions after upgr ### 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 were developed with it which will require adjustments. +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. + +> [!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! From 6d13530b4389d89d938de5d5e422e45aa27fffe5 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Wed, 11 Oct 2023 14:41:43 +0200 Subject: [PATCH 4/4] Add EFCore.PG note on NativeAOT opt-ins --- conceptual/EFCore.PG/release-notes/8.0.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/conceptual/EFCore.PG/release-notes/8.0.md b/conceptual/EFCore.PG/release-notes/8.0.md index dcc1ad770..7418dbc54 100644 --- a/conceptual/EFCore.PG/release-notes/8.0.md +++ b/conceptual/EFCore.PG/release-notes/8.0.md @@ -10,6 +10,20 @@ New features will be documented later. 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. +### 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 or on : + +PostgreSQL type | Default .NET type +---------------------------------------- | -------------------------- +JSON POCO mapping, JsonNode and subtypes | +Unmapped enums, ranges, multiranges | +Read PostgreSQL records as .NET tuples | + +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.