# Umbraco.Cms.Persistence.EFCore.SqlServer

SQL Server-specific EF Core provider for Umbraco CMS. Contains SQL Server migrations and provider setup for the EF Core persistence layer.

**Project Type**: Class Library (NuGet package)
**Target Framework**: net10.0
**Dependencies**: Umbraco.Cms.Persistence.EFCore

---

## 1. Architecture

### Project Purpose

This is a thin provider project that implements SQL Server-specific functionality for the EF Core persistence layer:

1. **Migration Provider** - Executes SQL Server-specific migrations
2. **Migration Provider Setup** - Configures DbContext to use SQL Server
3. **Migrations** - SQL Server-specific migration files for OpenIddict tables

### Folder Structure

```
Umbraco.Cms.Persistence.EFCore.SqlServer/
├── Migrations/
│   ├── 20230622184303_InitialCreate.cs          # No-op (NPoco creates tables)
│   ├── 20230807654321_AddOpenIddict.cs          # OpenIddict tables
│   ├── 20240403140654_UpdateOpenIddictToV5.cs   # OpenIddict v5 schema changes
│   ├── 20251006140751_UpdateOpenIddictToV7.cs   # Token Type column expansion
│   └── UmbracoDbContextModelSnapshot.cs         # Current model state
├── EFCoreSqlServerComposer.cs                   # DI registration
├── SqlServerMigrationProvider.cs                # IMigrationProvider impl
└── SqlServerMigrationProviderSetup.cs           # IMigrationProviderSetup impl
```

### Relationship with Parent Project

This project extends `Umbraco.Cms.Persistence.EFCore`:

- Implements `IMigrationProvider` interface defined in parent
- Implements `IMigrationProviderSetup` interface defined in parent
- Uses `UmbracoDbContext` from parent project
- Provider name: `Microsoft.Data.SqlClient` (from `Constants.ProviderNames.SQLServer`)

---

## 2. Commands

**For Git workflow and build commands**, see [repository root](../../CLAUDE.md).
**For EF Core migration commands**, see [parent project](../Umbraco.Cms.Persistence.EFCore/CLAUDE.md) (substitute `-p src/Umbraco.Cms.Persistence.EFCore.SqlServer`).

---

## 3. Key Components

### EFCoreSqlServerComposer (line 10-14)

Registers SQL Server implementations of `IMigrationProvider` and `IMigrationProviderSetup`.

### SqlServerMigrationProvider

Executes migrations via `MigrateAsync(EFCoreMigration)` or `MigrateAllAsync()`. Unlike SQLite sibling, no transaction check needed (SQL Server handles concurrent migrations natively).

### SqlServerMigrationProviderSetup (line 11-14)

Configures `DbContextOptionsBuilder` with `UseSqlServer` and migrations assembly.

---

## 4. Migrations

### Migration History

| Migration | Date | Purpose |
|-----------|------|---------|
| `InitialCreate` | 2023-06-22 | No-op - NPoco creates base tables |
| `AddOpenIddict` | 2023-08-07 | Creates OpenIddict tables |
| `UpdateOpenIddictToV5` | 2024-04-03 | Renames Type→ClientType, adds ApplicationType/JsonWebKeySet/Settings |
| `UpdateOpenIddictToV7` | 2025-10-06 | Expands Token.Type from nvarchar(50) to nvarchar(150) |

### OpenIddict Tables Created

Prefixed with `umbraco`: Applications, Authorizations, Scopes, Tokens (see SQLite sibling for details).

### SQL Server-Specific Differences from SQLite

1. **nvarchar types** - Uses `nvarchar(n)` and `nvarchar(max)` instead of TEXT
2. **v5 migration has actual changes** - Column rename and additions (SQLite handled differently)
3. **v7 migration has schema change** - Token.Type column expanded (SQLite didn't need this)

### Adding New Migrations

1. Configure SQL Server connection string in `src/Umbraco.Web.UI/appsettings.json`
2. Run migration command from repository root (see parent project docs)
3. **Critical**: Also add equivalent migration to `Umbraco.Cms.Persistence.EFCore.Sqlite`
4. Update `SqlServerMigrationProvider.GetMigrationType()` switch (line 27-35) if adding named migrations

---

## 5. Project-Specific Notes

### Named Migration Mapping

`SqlServerMigrationProvider.GetMigrationType()` (line 27-35) maps `EFCoreMigration` enum to migration types. Update both parent enum and this switch when adding named migrations.

### Transaction Handling

SQL Server handles concurrent migrations natively - no transaction check needed (unlike SQLite).

### Auto-Generated Files

`UmbracoDbContextModelSnapshot.cs` is regenerated by EF Core - do not edit manually.

---

## Quick Reference

### Essential Files

| File | Purpose |
|------|---------|
| `SqlServerMigrationProvider.cs` | Migration execution |
| `SqlServerMigrationProviderSetup.cs` | DbContext configuration |
| `EFCoreSqlServerComposer.cs` | DI registration |
| `Migrations/*.cs` | Migration files |

### Provider Name
`Constants.ProviderNames.SQLServer` = `"Microsoft.Data.SqlClient"`

### Related Projects
- **Parent**: `Umbraco.Cms.Persistence.EFCore` - Interfaces and base DbContext
- **Sibling**: `Umbraco.Cms.Persistence.EFCore.Sqlite` - SQLite equivalent
