<!-- GENERATED FILE - DO NOT EDIT This file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets). Source File: /readme.source.md To change this file edit the source file and then run MarkdownSnippets. -->

<img src="/src/icon.png" height="30px"> LocalDb

Provides a wrapper around SqlLocalDB to simplify running tests against Entity Framework or a raw SQL Database.<!-- singleLineInclude: intro. path: /docs/mdsource/intro.include.md -->

See Milestones for release notes.

SqlLocalDB is only supported on Windows

Sponsors

Entity Framework Extensions<!-- include: sponsors. path: /docs/mdsource/sponsors.include.md -->

Entity Framework Extensions is a major sponsor and is proud to contribute to the development this project.

Developed using JetBrains IDEs

<!-- endInclude -->

<!-- toc -->

Contents

• Why
  • Goals
  • Why not SQLite
  • Why not SQL Express or full SQL Server
  • Why not EntityFramework InMemory
• References
• Usage
  • Raw SqlConnection
  • EntityFramework Classic
  • EntityFramework Core
  • EntityFramework Core NUnit
  • EntityFramework Core xunit.v3
  • EntityFramework Core MSTest
  • EntityFramework Core TUnit
• LocalDB
• How this project works
  • Inputs
  • SqlInstance Startup Flow
  • Clean Directory Flow
  • Create SqlDatabase Flow
• Performance
  • Hardware
  • Scenarios
  • Results
  • Key Insights
• Debugging
• SqlLocalDb
• ReSharper Test Runner
• Credits<!-- endToc -->
• Design
• Raw Connection Usage
• EntityFramework Classic Usage
• EntityFramework Core Usage
• EntityFramework Core NUnit Usage
• EntityFramework Core xunit.v3 Usage
• EntityFramework Core MSTest Usage
• EntityFramework Core TUnit Usage
• EntityFramework Core Migrations
• Directory and name resolution
• Sql Management Studio
• Logging
• Template database size
• Template Re-generation
• DB auto offline
• Shutdown Timeout

NuGet packages

• https://www.nuget.org/packages/LocalDb/
• https://www.nuget.org/packages/EfLocalDb/
• https://www.nuget.org/packages/EfLocalDb.NUnit/
• https://www.nuget.org/packages/EfLocalDb.Xunit.V3/
• https://www.nuget.org/packages/EfLocalDb.MSTest/
• https://www.nuget.org/packages/EfLocalDb.TUnit/
• https://www.nuget.org/packages/EfClassicLocalDb/

Why

Goals

• Have a isolated SQL Server Database for each unit test method.
• Does not overly impact performance.
• Results in a running SQL Server Database that can be accessed via SQL Server Management Studio (or other tooling) to diagnose issues when a test fails.

Why not SQLite

• SQLite and SQL Server do not have compatible feature sets and there are incompatibilities between their query languages.

Why not SQL Express or full SQL Server

• Control over file location. SqlLocalDB connections support AttachDbFileName property, which allows developers to specify a database file location. SqlLocalDB will attach the specified database file and the connection will be made to it. This allows database files to be stored in a temporary location, and cleaned up, as required by tests.
• No installed service is required. Processes are started and stopped automatically when needed.
• Automatic cleanup. A few minutes after the last connection to this process is closed the process shuts down.
• Full control of instances using the Command-Line Management Tool: SqlLocalDB.exe.

Why not EntityFramework InMemory

• Difficult to debug the state. When debugging a test, or looking at the resultant state, it is helpful to be able to interrogate the Database using tooling
• InMemory is implemented with shared mutable state between instance. This results in strange behaviors when running tests in parallel, for example when creating keys.
• InMemory is not intended to be an alternative to SqlServer, and as such it does not support the full suite of SqlServer features. For example:
  • Does not support Timestamp/row version.
  • Does not validate constraints.

See the official guidance: InMemory is not a relational database.

References

• Which Edition of SQL Server is Best for Development Work?
• Introducing SqlLocalDB, an improved SQL Express
• SQL LocalDB 2022 Download
• SQL Server 2022 Cumulative Update required to update LocalDb to the latest version.
• SQL Server 2022 Express via Chocolatey: choco install sql-server-express

Usage

This project supports several approaches.

Raw SqlConnection

Interactions with SqlLocalDB via a SqlConnection.

Full Usage

EntityFramework Classic

Interactions with SqlLocalDB via Entity Framework Classic.

Full Usage

EntityFramework Core

Interactions with SqlLocalDB via Entity Framework Core.

Full Usage

EntityFramework Core NUnit

NUnit test base class wrapping EfLocalDb with Arrange-Act-Assert phase enforcement.

Full Usage

EntityFramework Core xunit.v3

xunit.v3 test base class wrapping EfLocalDb with Arrange-Act-Assert phase enforcement.

Full Usage

EntityFramework Core MSTest

MSTest test base class wrapping EfLocalDb with Arrange-Act-Assert phase enforcement.

Full Usage

EntityFramework Core TUnit

TUnit test base class wrapping EfLocalDb with Arrange-Act-Assert phase enforcement.

Full Usage

LocalDB

How MS SqlServer LocalDB is structured

graph TB
    subgraph PM["Physical Machine (Windows)"]
        subgraph SQLLocalDB["SqlServer LocalDB"]
            subgraph Instance1["LocalDB Instance: MSSQLLocalDB"]
                DB1A[(DB: MyApp)]
                DB1B[(DB: Te