---
title: "Introduction to RoomSharp"
description: "Type-safe, source-generated data layer for modern .NET applications."
canonical: "https://roomsharp.dev/docs/v0.5.3/index"
source: "src/content/v0.5.3/index.mdx"
---

# Introduction to RoomSharp

RoomSharp is a .NET data layer inspired by Android's Room database. It supports .NET 8/9/10 and combines a Roslyn source generator, attribute-driven models, and lightweight database providers (SQLite, SQL Server, PostgreSQL, MySQL) to produce zero-reflection DAOs, migrations, and schema builders, while still letting you drop down to raw ADO.NET when needed.

<Tip title="Key Philosophy">
Compile-time code generation instead of runtime reflection. RoomSharp analyzes your entity classes and DAO interfaces at build time to generate optimized, type-safe data access code.
</Tip>

## Current Version

The current documentation targets **RoomSharp 0.5.3**.

Key changes since the 0.4.7 documentation:

- Smarter generated DAO lifecycle support for `[SoftDelete]`, `[Encrypted]`, and `[Auditable]` entities.
- More robust generated transaction wrappers, including `CancellationToken` propagation.
- Compile-time diagnostics for unsupported `[Transaction]` streaming methods.
- Safer SQL parameter rewriting in generated query preparation.
- Runtime hardening for transactions, seeders, global filters, paging, and provider-specific FTS SQL.
- QueryExtensions improvements including filtered includes, `LockForUpdate()`, and a cleaner fluent-query core.

See the [Changelog](/docs/v0.5.3/changelog) for the complete release history.

## Why RoomSharp?

- **Source-generated DAOs** – compile-time codegen (no reflection) for queries, inserts, updates, deletes, and projections.
- **Multi-provider runtime** – common abstractions over SQLite, SQL Server, PostgreSQL, and MySQL, each with tuned dialect helpers.
- **Builder-first configuration** – tune journal mode, register callbacks, enable multi-instance invalidation, choose concurrency mode, and auto-close idle connections.
- **Transaction-aware** – explicit `RunInTransaction*` helpers plus `[Transaction]` support in generated DAOs (sync/async).
- **Rich annotations** – `[Entity]`, `[Embedded]`, `[Relation]`, `[DatabaseView]`, `[TypeConverter]`, `[Index]`, etc.
- **Migrations baked in** – combine handwritten migrations, auto-migration metadata, and fallback destructive mode.
- **Utilities included** – LiveData, Flow, paging sources, raw query helpers, bulk insert extensions, and more.

## Who is this for?

RoomSharp is designed for developers who:

- Want **compile-time safety and source-generated data access** without the runtime overhead of full ORMs like EF Core.
- Build **desktop, mobile, or backend applications** where database control, predictability, and performance matter.
- Rely heavily on **SQLite or file-based databases** (common in mobile and embedded environments) and still need clear, disciplined concurrency guarantees.
- Prefer explicit SQL, migrations, and schema evolution over implicit runtime behavior.

## Supported Providers

| Provider | Package | NuGet Dependency |
|----------|---------|------------------|
| SQLite | `RoomSharp` | `Microsoft.Data.Sqlite` |
| SQL Server | `RoomSharp.SqlServer` | `Microsoft.Data.SqlClient` |
| PostgreSQL | `RoomSharp.PostgreSql` | `Npgsql` |
| MySQL/MariaDB | `RoomSharp.MySql` | `MySqlConnector` |

Every provider implements `IDatabaseProvider` so it can be swapped in via `RoomDatabaseBuilder<T>.UseProvider`.

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

## Ecosystem Overview

| Package | Description |
|---------|-------------|
| **RoomSharp** | Core package with SQLite provider |
| **RoomSharp.SqlServer** | SQL Server provider |
| **RoomSharp.PostgreSql** | PostgreSQL provider |
| **RoomSharp.MySql** | MySQL/MariaDB provider |
| **RoomSharp.Cli** | CLI tool for scaffolding and migrations |
| **RoomSharp.DependencyInjection** | ASP.NET Core DI integration |
| **RoomSharp.QueryExtensions** | Dapper-like raw SQL helpers |

## Quick Start

```csharp
using RoomSharp.Attributes;
using RoomSharp.Core;
using RoomSharp.Extensions;

// 1. Define your entity
[Entity(TableName = "users")]
public class User
{
    [PrimaryKey(AutoGenerate = true)]
    public long Id { get; set; }

    [Unique]
    public required string Email { get; set; }
    public string? Name { get; set; }
}

// 2. Define your DAO
[Dao]
public interface IUserDao
{
    [Insert] long Insert(User user);

    [Query("SELECT * FROM users WHERE Email = :email")]
    Task<User?> FindByEmailAsync(string email);

    [Update] int Update(User user);

    [Transaction]
    async Task<long> UpsertAsync(User user)
    {
        var existing = await FindByEmailAsync(user.Email);
        if (existing is null)
        {
            return Insert(user);
        }

        existing.Name = user.Name;
        Update(existing);
        return existing.Id;
    }
}

// 3. Define your database
[Database(Version = 1, Entities = [typeof(User)])]
public abstract class AppDatabase(IDatabaseProvider provider, ILogger? logger = null)
    : RoomDatabase(provider, logger)
{
    public abstract IUserDao UserDao { get; }
}

// 4. Build and use
var db = RoomDatabase.Builder<AppDatabaseImpl>()
    .UseSqlite("app.db")
    .AddCallback(new LoggingCallback(logger))
    .SetJournalMode(JournalMode.WAL)
    .EnableMultiInstanceInvalidation()
    .SetAutoCloseTimeout(TimeSpan.FromMinutes(5))
    .Build();

var userId = db.UserDao.Insert(new User { Email = "john@acme.dev", Name = "John" });
```

<Tip>
What just happened? The source generator created `AppDatabaseImpl` and `IUserDaoImpl` with fully optimized, type-safe implementations. No reflection, no runtime overhead.
</Tip>

## CLI Quick Start

```bash
# Install CLI
dotnet tool install -g RoomSharp.Cli

# Setup project
room make:config --provider sqlite --connection "Data Source=app.db" --ns MyApp.Data
room make:entity User --table=users
room make:dao User --entity=User
room make:database AppDatabase --version=1 --entities=User

# Apply migrations
room migrate:up -b
```

## Next Steps

- [Installation Guide](/docs/v0.5.3/installation) - Set up RoomSharp in your project
- [Entities](/docs/v0.5.3/entities) - Learn how to define your data models
- [DAO Interfaces](/docs/v0.5.3/dao-interfaces) - Create data access objects
- [CLI Overview](/docs/v0.5.3/cli-overview) - Learn the CLI commands
- [Changelog](/docs/v0.5.3/changelog) - Review release history