---
title: "Installation"
description: "Install RoomSharp packages and set up your project."
canonical: "https://roomsharp.dev/docs/v0.5.4/installation"
source: "src/content/v0.5.4/installation.mdx"
---

# Installation

RoomSharp is distributed as a set of NuGet packages. Choose the core package and the provider(s) that match your target database.

<Tip>
When using multiple RoomSharp packages together, keep them on the same version whenever possible. RoomSharp uses synchronized ecosystem versioning for the core package family starting with `v0.5.3`. See the [Release Model](/docs/v0.5.4/release-model) for details.
</Tip>

## Core Package (Includes SQLite)

```bash
dotnet add package RoomSharp
```

The `RoomSharp` package includes the core runtime, SQLite support, and the source generator used to create database and DAO implementations at build time.

<Note>
You normally do not need to reference `RoomSharp.SourceGenerator` directly. The generator is packaged with `RoomSharp` as an analyzer for normal application projects.
</Note>

## Database Providers

### SQL Server

```bash
dotnet add package RoomSharp.SqlServer
```

### PostgreSQL

```bash
dotnet add package RoomSharp.PostgreSql
```

### MySQL / MariaDB

```bash
dotnet add package RoomSharp.MySql
```

<Note>
Older RoomSharp versions used `MySql.Data`. The MySQL provider now uses **MySqlConnector** for performance and licensing considerations.
</Note>

## Optional Packages

### QueryExtensions

```bash
dotnet add package RoomSharp.QueryExtensions
```

Use this when you want fluent queries, raw SQL helpers, streaming, multi-mapping, row readers, filtered includes, query caching, or `LockForUpdate()`.

### Dependency Injection

```bash
dotnet add package RoomSharp.DependencyInjection
```

Use this for ASP.NET Core or any application that wants `IServiceCollection` registration for databases, DAOs, health checks, encryption providers, audit context, pooled databases, or keyed services.

### Reactive Queries

```bash
dotnet add package RoomSharp.Reactive
```

Use this for observable queries, query cache, computed views, and UI collection binding.

### WinForms Reactive Binding

```bash
dotnet add package RoomSharp.Reactive.WinForms
```

Use this only for WinForms applications that need `BindingList`, `BindingSource`, or `DataGridView` helpers on top of `RoomSharp.Reactive`.

### Command-Line Interface (CLI)

```bash
dotnet tool install --global RoomSharp.Cli
```

<Tip>
The CLI follows the RoomSharp ecosystem release model. For reproducible builds, pin package versions in your project and update the global tool intentionally.
</Tip>

## Common Install Sets

### SQLite Application

```bash
dotnet add package RoomSharp
```

### SQL Server Application

```bash
dotnet add package RoomSharp
dotnet add package RoomSharp.SqlServer
```

### ASP.NET Core With DI

```bash
dotnet add package RoomSharp
dotnet add package RoomSharp.DependencyInjection
dotnet add package RoomSharp.QueryExtensions
```

Add the provider package you need, for example:

```bash
dotnet add package RoomSharp.PostgreSql
```

### Desktop UI With Reactive Binding

```bash
dotnet add package RoomSharp
dotnet add package RoomSharp.Reactive
```

For WinForms:

```bash
dotnet add package RoomSharp.Reactive.WinForms
```

### CLI Tooling

```bash
dotnet tool install --global RoomSharp.Cli
```

The CLI should be run inside a project that references `RoomSharp`.

## Package Overview

| Package | Type | Description |
|---------|------|-------------|
| **RoomSharp** | Core runtime | Core package with SQLite provider and bundled source generator |
| **RoomSharp.SqlServer** | Provider | SQL Server provider using `Microsoft.Data.SqlClient` |
| **RoomSharp.PostgreSql** | Provider | PostgreSQL provider using `Npgsql` |
| **RoomSharp.MySql** | Provider | MySQL/MariaDB provider using `MySqlConnector` |
| **RoomSharp.DependencyInjection** | Integration | ASP.NET Core DI registration, DAOs, health checks, pooling, keyed services, encryption, and audit setup |
| **RoomSharp.QueryExtensions** | Extension | Fluent queries, raw SQL, streaming, row readers, multi-mapping, filtered includes, caching, and pessimistic locking |
| **RoomSharp.Reactive** | Extension | Observable queries, query cache, computed views, and UI binding helpers |
| **RoomSharp.Reactive.WinForms** | UI binding | WinForms helpers for `BindingList`, `BindingSource`, and `DataGridView` |
| **RoomSharp.Cli** | Global tool | Scaffolding, migrations, database inspection, query execution, seeding, and diagrams |
| **RoomSharp.SourceGenerator** | Analyzer | Source generator package; usually consumed through `RoomSharp` |

## Target Frameworks

RoomSharp supports:
- .NET 8.0
- .NET 9.0
- .NET 10.0

Use the same target framework support expectation for the ecosystem packages unless a UI-specific package, such as WinForms binding, is constrained by the UI framework.

## Builder Configuration

`RoomDatabaseBuilder<T>` exposes fluent helpers for configuration:

| Extension | Effect |
|-----------|--------|
| `UseSqlite(string dbPath)` | Select SQLite and connection string |
| `UseProvider(IDatabaseProvider, string)` | Select custom provider |
| `SetVersion(int)` | Override version from `[Database]` |
| `SetEntities(Type[])` | Override entities from `[Database]` |
| `AddMigrations(params Migration[])` | Register manual migrations |
| `FallbackToDestructiveMigration()` | Drop & recreate on downgrade |
| `AddCallback(RoomDatabaseCallback)` | Receive lifecycle events |
| `SetJournalMode(JournalMode)` | Configure SQLite journal mode |
| `EnableMultiInstanceInvalidation()` | Multi-process WAL usage |
| `SetAutoCloseTimeout(TimeSpan)` | Auto-close idle connections |
| `SetMaxParallelConnections(int)` | Max connections for Parallel mode |
| `UseConnectionFactory(Func<DbConnection>)` | Custom connection factory |

> **Note:** `ConcurrencyMode` is now set via the `[Database]` attribute, not the builder.

Provider packages may add provider-specific builder helpers such as `UseSqlServer(...)`, `UsePostgres(...)`, or `UseMySql(...)`. See [Database Providers](/docs/v0.5.4/database-providers) for provider-specific configuration.

## Example Configuration

```csharp
var db = RoomDatabase.Builder<AppDatabaseImpl>()
    .UseSqlite("app.db")
    .SetVersion(2)
    .AddMigrations(new UserMigration_1_2())
    .AddCallback(new LoggingCallback(logger))
    .SetJournalMode(JournalMode.WAL)
    .EnableMultiInstanceInvalidation()
    .SetAutoCloseTimeout(TimeSpan.FromMinutes(2))
    .Build();
```

<Tip>
When `SetAutoCloseTimeout` is used, RoomSharp closes idle connections in the background and reopens them transparently the next time a DAO method runs.
</Tip>

## Logging Callback

Create a logging callback to receive lifecycle events:

```csharp
public class LoggingCallback : RoomDatabaseCallback
{
    private readonly ILogger _logger;

    public LoggingCallback(ILogger logger) => _logger = logger;

    public override void OnCreate(DbConnection connection)
    {
        _logger.LogInformation("Database created");
    }

    public override void OnOpen(DbConnection connection)
    {
        _logger.LogInformation("Database opened");
    }

    public override void OnDestructiveMigration(DbConnection connection)
    {
        _logger.LogWarning("Destructive migration performed");
    }
}
```

## Next Steps

- [Entities](/docs/v0.5.4/entities) - Define your data models
- [DAO Interfaces](/docs/v0.5.4/dao-interfaces) - Create data access objects
- [Dependency Injection](/docs/v0.5.4/dependency-injection) - Register databases and DAOs in `IServiceCollection`
- [QueryExtensions](/docs/v0.5.4/query-extensions) - Use fluent queries, raw SQL, and relation includes
- [Reactive Queries](/docs/v0.5.4/reactive-queries) - Add observable queries and UI binding
- [CLI Overview](/docs/v0.5.4/cli-overview) - Learn CLI commands