-
Notifications
You must be signed in to change notification settings - Fork 76
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Some release notes and breaking changes for 8.0 (#306)
- Loading branch information
Showing
6 changed files
with
115 additions
and
41 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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)) | ||
{ | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters