Mastering Multi-Tenancy with the Unit of Work Pattern

Building a SaaS application means one thing above all: serving multiple customers (tenants) from the same system. Multi-tenancy gives us efficiency and scalability, but it also comes with challenges around data isolation, transaction safety, and maintainability.

That’s where the Unit of Work (UoW) pattern comes in. Together, multi-tenancy and Unit of Work form a strong foundation for building secure, scalable, and clean SaaS backends.

1. Quick Recap: What is Multi-Tenancy?

Multi-tenancy is a software architecture pattern where a single application instance serves multiple tenants. Each tenant is logically isolated, but the underlying code and infrastructure are shared.

Benefits

Cost Efficiency: Shared infrastructure reduces hosting and maintenance costs.
Scalability: Scaling one app is easier than managing multiple isolated instances.
Centralized Management: One codebase for all tenants means faster updates and bug fixes.

2. Multi-Tenancy Models

There are three common models for implementing multi-tenancy:

Database-per-Tenant
- Each tenant gets its own database.
- Pros: Strong isolation, easy data backup.
- Cons: Harder to manage at scale (many connection strings, migrations).
Schema-per-Tenant
- All tenants share a database, but each tenant has its own schema.
- Pros: Balance between isolation and management.
- Cons: Still requires schema management complexity.
Shared Schema
- All tenants share one database and one schema. Tenant rows are separated by a TenantId column.
- Pros: Resource-efficient, simplest to scale horizontally.
- Cons: Requires strict query filters to avoid data leakage.

3. What is the Unit of Work Pattern?

The Unit of Work pattern is a way to track changes during a business transaction and commit them as a single unit.

Instead of repositories or services committing changes individually, Unit of Work:

Groups all changes under one transaction.
Commits them together (atomicity).
Rolls back safely on errors.

Think of it like a "shopping cart" for database changes: you gather all the operations you need, then check out (commit) once at the end.

4. Why Combine Multi-Tenancy with Unit of Work?

Multi-tenancy introduces complexity: each request belongs to a tenant, and that tenant’s data must be isolated in every transaction.

Here’s why Unit of Work helps:

Tenant Isolation: Each UoW instance is scoped to one tenant.
Atomic Transactions: Ensures tenant-specific changes commit together.
Centralized Tenant Context: Inject tenant info automatically into repositories.
Cleaner Codebase: Keeps data access and tenant handling consistent across the app.

5. Architecture Design

Here’s a high-level architecture combining both patterns:

\[ Request ]
↓
\[ Tenant Resolver Middleware ]
↓
\[ Application Layer ]
↓
\[ Unit of Work (per tenant request) ]
↓
\[ Repositories with Tenant Context ]
↓
\[ Database (per-tenant / schema / shared schema) ]

Flow

Resolve TenantId from subdomain, request header, or JWT.
Initialize a Unit of Work bound to that tenant.
Repositories auto-apply the tenant context.
At the end of the request, commit or rollback the UoW.

6. Implementation in C#

Here’s a simplified version using Entity Framework Core.

Tenant Context

public class TenantContext
{
    public string TenantId { get; set; }
    public string ConnectionString { get; set; }
}

Unit of Work

public interface IUnitOfWork : IDisposable
{
    Task<int> CommitAsync();
}

public class UnitOfWork : IUnitOfWork
{
    private readonly TenantDbContext _context;

    public UnitOfWork(TenantDbContext context)
    {
        _context = context;
    }

    public async Task<int> CommitAsync()
    {
        return await _context.SaveChangesAsync();
    }

    public void Dispose() => _context.Dispose();
}

Tenant-Aware DbContext

public class TenantDbContext : DbContext
{
    private readonly TenantContext _tenant;

    public TenantDbContext(DbContextOptions<TenantDbContext> options, TenantContext tenant)
        : base(options)
    {
        _tenant = tenant;
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Apply tenant filter for shared-schema model
        foreach (var entity in modelBuilder.Model.GetEntityTypes())
        {
            if (typeof(ITenantEntity).IsAssignableFrom(entity.ClrType))
            {
                modelBuilder.Entity(entity.ClrType).HasQueryFilter(
                    e => EF.Property<string>(e, "TenantId") == _tenant.TenantId
                );
            }
        }
        base.OnModelCreating(modelBuilder);
    }
}

Repository Example

public interface ICustomerRepository
{
    Task AddAsync(Customer customer);
    Task<Customer?> GetByIdAsync(Guid id);
}

public class CustomerRepository : ICustomerRepository
{
    private readonly TenantDbContext _context;

    public CustomerRepository(TenantDbContext context)
    {
        _context = context;
    }

    public async Task AddAsync(Customer customer)
    {
        customer.TenantId = _context.TenantId; // enforce tenant scope
        await _context.Customers.AddAsync(customer);
    }

    public async Task<Customer?> GetByIdAsync(Guid id)
    {
        return await _context.Customers.FirstOrDefaultAsync(c => c.Id == id);
    }
}

Application Service Example

public class CustomerService
{
    private readonly ICustomerRepository _repository;
    private readonly IUnitOfWork _unitOfWork;

    public CustomerService(ICustomerRepository repository, IUnitOfWork unitOfWork)
    {
        _repository = repository;
        _unitOfWork = unitOfWork;
    }

    public async Task CreateCustomerAsync(Customer customer)
    {
        await _repository.AddAsync(customer);
        await _unitOfWork.CommitAsync();
    }
}

7. Challenges & Best Practices

Tenant Context Propagation: Always resolve tenant at the request boundary. Don’t pass it around manually.
Transaction Boundaries: One Unit of Work per request is a good rule of thumb.
Performance Monitoring: Track per-tenant query load to avoid “noisy neighbor” issues.
Security: Enforce tenant filters at the ORM level to avoid accidental cross-tenant queries.
Testing: Write integration tests simulating multiple tenants to ensure isolation.

8. Conclusion

Combining multi-tenancy architecture with the Unit of Work pattern gives your SaaS application:

Strong data isolation.
Reliable transaction safety.
Cleaner, maintainable code.

As SaaS adoption grows, this architecture will help you scale confidently while keeping each tenant’s data safe and consistent.