-
Notifications
You must be signed in to change notification settings - Fork 76
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.
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
Some release notes and breaking changes for 8.0 #306
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
# 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. | ||
|
||
### 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)) | ||
{ | ||
} | ||
} | ||
``` |
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -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, <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> | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. No strong feelings here but both terms seem to be used (some search results). I'll leave like that for now but if you feel strongly about it I can change. |
||||||
|
||||||
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). | ||||||
roji marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
## Breaking changes | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm assuming we're still missing quite a few things here, including cidr/inet changes etc? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Absolutely, this is just a first round. I'll be submitting more PRs. |
||||||
|
||||||
```c# | ||||||
var builder = new NpgsqlDataSourceBuilder("<connection string>"); | ||||||
builder.UseSystemTextJson(); | ||||||
await using var dataSource = builder.Build(); | ||||||
``` | ||||||
### <a name="dynamic-optin">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 <xref:Npgsql.NpgsqlDataSourceBuilder> or on <xref:Npgsql.NpgsqlConnection.GlobalTypeMapper?displayProperty=nameWithType>: | ||||||
|
||||||
```c# | ||||||
NpgsqlConnection.GlobalTypeMapper.UseSystemTextJson(); | ||||||
``` | ||||||
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> | ||||||
|
||||||
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. | ||||||
roji marked this conversation as resolved.
Show resolved
Hide resolved
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should mention nullable parameter support in copy and parameters
npgsql/npgsql#1965
npgsql/npgsql#3679
There is also some info that needs changes here, as we now do support sending nulls
https://www.npgsql.org/doc/basic-usage.html#strongly-typed-parameters
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can decide to mention something about the polymorphic json support npgsql/npgsql#4862
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh absolutely, this is just a first round - we definitely need a lot more release notes; I'll be working on that (putting your suggestions in my notes).