Skip to content

Commit 3f1c118

Browse files
authored
Document SQL Server compatibility level bump (#5352)
Document dotnet/efcore#38198
1 parent c0d05f0 commit 3f1c118

2 files changed

Lines changed: 38 additions & 0 deletions

File tree

entity-framework/core/what-is-new/ef-core-11.0/breaking-changes.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ This page documents API and behavior changes that have the potential to break ex
2323
|:--------------------------------------------------------------------------------------------------------------- | -----------|
2424
| [Sync I/O via the Azure Cosmos DB provider has been fully removed](#cosmos-nosync) | Medium |
2525
| [Microsoft.Data.SqlClient has been updated to 7.0](#sqlclient-7) | Medium |
26+
| [SQL Server compatibility level now defaults to 160](#sqlserver-compatibility-level-160) | Low |
2627
| [EF Core now throws by default when no migrations are found](#migrations-not-found) | Low |
2728
| [`EFOptimizeContext` MSBuild property has been removed](#ef-optimize-context-removed) | Low |
2829
| [EF tools packages no longer reference Microsoft.EntityFrameworkCore.Design](#ef-tools-no-design-dep) | Low |
@@ -85,6 +86,39 @@ No code changes are required beyond adding this package reference. If you use `S
8586

8687
## Low-impact changes
8788

89+
<a name="sqlserver-compatibility-level-160"></a>
90+
91+
### SQL Server compatibility level now defaults to 160
92+
93+
[Tracking Issue #38198](https://github.com/dotnet/efcore/issues/38198)
94+
95+
#### Old behavior
96+
97+
Previously, when using <xref:Microsoft.EntityFrameworkCore.SqlServerDbContextOptionsExtensions.UseSqlServer*> without explicitly configuring a SQL Server compatibility level, EF Core defaulted to compatibility level 150, corresponding to SQL Server 2019.
98+
99+
#### New behavior
100+
101+
Starting with EF Core 11.0, <xref:Microsoft.EntityFrameworkCore.SqlServerDbContextOptionsExtensions.UseSqlServer*> defaults to compatibility level 160, corresponding to SQL Server 2022. This allows EF to generate SQL which uses SQL Server 2022 features by default. For example, some queries now use `LEAST` and `GREATEST`, including translations for `Math.Min`, `Math.Max`, <xref:Microsoft.EntityFrameworkCore.RelationalDbFunctionsExtensions.Least*>, <xref:Microsoft.EntityFrameworkCore.RelationalDbFunctionsExtensions.Greatest*>, and some `Take`/`Skip` patterns.
102+
103+
If your database runs on SQL Server 2019 or older, or is configured with a compatibility level lower than 160, some SQL generated by EF Core may no longer be supported by the database.
104+
105+
#### Why
106+
107+
SQL Server 2022 has been available for several years, and using compatibility level 160 by default allows EF Core to generate simpler and more efficient SQL for newer SQL Server versions.
108+
109+
#### Mitigations
110+
111+
If your database does not support compatibility level 160, configure EF Core to use the compatibility level supported by your database:
112+
113+
```csharp
114+
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
115+
{
116+
optionsBuilder.UseSqlServer("<connection string>", o => o.UseCompatibilityLevel(150));
117+
}
118+
```
119+
120+
For more information, see the [SQL Server compatibility level documentation](xref:core/providers/sql-server/index#compatibility-level).
121+
88122
<a name="migrations-not-found"></a>
89123

90124
### EF Core now throws by default when no migrations are found

entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -500,6 +500,10 @@ In addition, `EF.Functions.DateTrunc()` is now available for truncating `DateTim
500500

501501
For the complete list of date/time function translations, see the [SQL Server function mappings page](xref:core/providers/sql-server/functions).
502502

503+
### Other changes
504+
505+
* <xref:Microsoft.EntityFrameworkCore.SqlServerDbContextOptionsExtensions.UseSqlServer*> now defaults to compatibility level 160 (SQL Server 2022), enabling SQL Server 2022-specific translations such as `LEAST` and `GREATEST` by default; see the [breaking change note](xref:core/what-is-new/ef-core-11.0/breaking-changes#sqlserver-compatibility-level-160) for more information.
506+
503507
## Cosmos DB
504508

505509
<a name="cosmos-complex-types"></a>

0 commit comments

Comments
 (0)