Docs related to version 7 GUID generation

See npgsql/efcore.pg#3249
npgsql · Sep 1, 2024 · b4bd805 · b4bd805
1 parent 62714ec
commit b4bd805
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 3 deletions.
diff --git a/conceptual/EFCore.PG/modeling/generated-properties.md b/conceptual/EFCore.PG/modeling/generated-properties.md
@@ -92,17 +92,17 @@ protected override void OnModelCreating(ModelBuilder modelBuilder)
 
 ## GUID/UUID Generation
 
-By default, for GUID key properties, a random GUID is generated client-side by the EF provider and sent to the database.
+By default, for GUID key properties, a GUID is generated client-side by the EF provider and sent to the database. From version 9.0 and onwards, these GUIDs are sequential (version 7), which are more optimized for database indexes (before version 9.0, these GUIDs were random).
 
-To generate GUID's client-side for non-key properties, configure them as follows:
+To have the provider generate GUIDs client-side for **non-key** properties, configure them as follows:
 
 ```c#
 protected override void OnModelCreating(ModelBuilder modelBuilder)
 {
  modelBuilder
  .Entity<Blog>()
  .Property(b => b.SomeGuidProperty)
- .HasValueGenerator<GuidValueGenerator>();
+ .HasValueGenerator<NpgsqlSequentialGuidValueGenerator>();
 }
 ```
 

diff --git a/conceptual/EFCore.PG/release-notes/9.0.md b/conceptual/EFCore.PG/release-notes/9.0.md
@@ -0,0 +1,25 @@
+# 9.0 Release Notes
+
+Npgsql.EntityFrameworkCore.PostgreSQL version 9.0 is under development; previews are available on [nuget.org](https://www.nuget.org/packages/Npgsql.EntityFrameworkCore.PostgreSQL).
+
+## UUIDv7 GUIDs are generated by default
+
+When your entity types have a `Guid` key, EF Core by default generates key values for new entities client-side - in .NET - before inserting those entity types to the database; this can be better for performance in some situations. Before version 9.0, the provider generated random GUIDs (version 4) by calling the .NET [`Guid.NewGuid()`](https://learn.microsoft.com/en-us/dotnet/api/system.guid.newguid?view=net-8.0#system-guid-newguid) function. Unfortunately, random GUIDs aren't ideal for database indexing and can cause performance issues.
+
+Version 9.0 of the provider now generates the recently standardized version 7 GUIDs, which is a sequential GUID type that's more appropriate for database indexes and improves their performance. This new behavior is by default and will take effect simply by upgrading the provider version.
+
+See [this post](https://www.cybertec-postgresql.com/en/unexpected-downsides-of-uuid-keys-in-postgresql) for more details and performance numbers on random vs. sequential GUIDs.
+
+Thanks to [@ChrisJollyAU ](https://github.com/ChrisJollyAU) and [@Timovzl ](https://github.com/Timovzl) for contributing this improvement!
+
+## Contributors
+
+A big thank you to all the following people who contributed to the 9.0 release!
+
+### [Milestone 9.0.0](https://github.com/npgsql/efcore.pg/milestone/61?closed=1)
+
+Contributor | Assigned issues
+------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------
+[@roji](https://github.com/roji) | [34](https://github.com/Npgsql/efcore.pg/issues?q=is%3Aissue+milestone%3A8.0.0+is%3Aclosed+assignee%3Aroji)
+[@ChrisJollyAU](https://github.com/ChrisJollyAU) | [1](https://github.com/Npgsql/efcore.pg/issues?q=is%3Aissue+milestone%3A8.0.0+is%3Aclosed+assignee%3AChrisJollyAU)
+[@Timovzl](https://github.com/Timovzl) | [1](https://github.com/Npgsql/efcore.pg/issues?q=is%3Aissue+milestone%3A8.0.0+is%3Aclosed+assignee%3ATimovzl)