Skip to content

Commit c9f9ea3

Browse files
Shay RojanskyCopilot
andcommitted
Document SQL Server compatibility level bump
Document dotnet/efcore#38198 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent c0d05f0 commit c9f9ea3

2 files changed

Lines changed: 51 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: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,23 @@ For the full `JSON_PATH_EXISTS` SQL Server documentation, see [`JSON_PATH_EXISTS
262262

263263
## SQL Server
264264

265+
<a name="sql-server-compatibility-level-160"></a>
266+
267+
### Default compatibility level changed to SQL Server 2022
268+
269+
When using <xref:Microsoft.EntityFrameworkCore.SqlServerDbContextOptionsExtensions.UseSqlServer*> without explicitly configuring a SQL Server compatibility level, EF Core now defaults to compatibility level 160 (SQL Server 2022), rather than 150 (SQL Server 2019). This enables SQL Server 2022-specific SQL translations by default.
270+
271+
For example, `Math.Min`, `Math.Max`, <xref:Microsoft.EntityFrameworkCore.RelationalDbFunctionsExtensions.Least*>, <xref:Microsoft.EntityFrameworkCore.RelationalDbFunctionsExtensions.Greatest*>, and `Min`/`Max` over inline or primitive collections can now translate to `LEAST` and `GREATEST` by default. EF can also use `LEAST` to simplify some queries with multiple `Take` operators, or with `Skip` and `Take`:
272+
273+
```sql
274+
SELECT [c].[CustomerID], [c].[ContactName]
275+
FROM [Customers] AS [c]
276+
ORDER BY [c].[ContactTitle], [c].[ContactName]
277+
OFFSET @p ROWS FETCH NEXT LEAST(@p1, @p2) ROWS ONLY
278+
```
279+
280+
If your database is SQL Server 2019 or older, or has a compatibility level lower than 160, configure EF's SQL Server compatibility level explicitly. For more information, see the [breaking change note](xref:core/what-is-new/ef-core-11.0/breaking-changes#sqlserver-compatibility-level-160) and the [SQL Server provider documentation](xref:core/providers/sql-server/index#compatibility-level).
281+
265282
<a name="sqlserver-vector-search"></a>
266283

267284
### VECTOR_SEARCH() and vector indexes

0 commit comments

Comments
 (0)