---
title: "Installation"
description: "Install RoomSharp packages and set up your project."
canonical: "https://roomsharp.dev/docs/v0.4.7/installation"
source: "src/content/v0.4.7/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.

## Core Package (Includes SQLite)

```bash
dotnet add package RoomSharp
```

## 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

### Query Extensions (Raw SQL Helpers)

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

### Dependency Injection (ASP.NET Core)

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

### Command-Line Interface (CLI)

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

<Tip>
The CLI is versioned alongside the core packages and follows the same migration compatibility guarantees.
</Tip>

## Package Overview

| Package | Description | Dependencies |
|---------|-------------|--------------|
| **RoomSharp** | Core package with SQLite provider | `Microsoft.Data.Sqlite` |
| **RoomSharp.SqlServer** | SQL Server provider | `Microsoft.Data.SqlClient` |
| **RoomSharp.PostgreSql** | PostgreSQL provider | `Npgsql` |
| **RoomSharp.MySql** | MySQL/MariaDB provider | `MySqlConnector` |
| **RoomSharp.Cli** | CLI tool for scaffolding | - |
| **RoomSharp.DependencyInjection** | ASP.NET Core DI | - |
| **RoomSharp.QueryExtensions** | Dapper-like raw SQL | - |

## Target Frameworks

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

## 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.

## 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.4.7/entities) - Define your data models
- [DAO Interfaces](/docs/v0.4.7/dao-interfaces) - Create data access objects
- [CLI Overview](/docs/v0.4.7/cli-overview) - Learn CLI commands