MicroORM
Documentation menu

Getting started

1. Install

MicroORM isn't published as a package. Clone the repository, reference the project from yours, and add the ADO.NET provider for your database:

git clone https://github.com/HilthonTT/MicroORM.git
dotnet add reference MicroORM/src/MicroORM/MicroORM.csproj
dotnet add package Npgsql                     # PostgreSQL
# or: Microsoft.Data.Sqlite, Microsoft.Data.SqlClient, MySqlConnector

2. Create a MicroDb

MicroDb is the entry point. It is thread-safe and meant to live for the whole application, for example as a singleton in dependency injection. Give it a dialect and a way to get connections:

using MicroORM.Configuration;
using MicroORM.Dialects;
using MicroORM.Mapping;
using MicroORM.Sessions;
 
// From a connection factory. MicroORM opens and closes each connection; the provider pools them.
var db = new MicroDb(SqlDialect.SqlServer, () => new SqlConnection(connectionString));
 
// From a DbDataSource (Npgsql's recommended pattern).
await using var dataSource = NpgsqlDataSource.Create(connectionString);
var db = new MicroDb(SqlDialect.PostgreSql, dataSource, new MicroOptions
{
    Naming = NamingConvention.SnakeCase,   // UserId <-> user_id
});

With ASP.NET Core:

builder.Services.AddSingleton(_ => new MicroDb(
    SqlDialect.PostgreSql,
    NpgsqlDataSource.Create(builder.Configuration.GetConnectionString("Default")!),
    new MicroOptions { Naming = NamingConvention.SnakeCase }));

Namespaces

Each area of MicroORM has its own namespace. Import the ones you use:

NamespaceMain types
MicroORM.SessionsMicroDb, MicroTransaction, MicroSession, ResultSets
MicroORM.DialectsSqlDialect
MicroORM.ConfigurationMicroOptions, CommandLog
MicroORM.SqlSql (interpolated SQL), RenderedSql
MicroORM.QueryingTable<T>, Query<T>, Projection<T, TResult>, UpdateBuilder<T>
MicroORM.MappingNamingConvention, EntityBuilder<T>, EntityMap, ValueGeneration
MicroORM.MaterializationRow
MicroORM.TypeHandlersTypeHandler<T>, JsonTypeHandler<T>
MicroORM.ProceduresProcedureParameters, DbTypes
MicroORM.ExceptionsMicroConcurrencyException

If your own code lives in a namespace that starts with MicroORM., the name Sql resolves to the MicroORM.Sql namespace. Add using Sql = MicroORM.Sql.Sql; after your namespace line.

3. Describe an entity

Any class with public properties works. No base class or attributes are required:

public class Customer
{
    public int Id { get; set; }                 // key by convention; database-generated
    public string Name { get; set; } = "";
    public string? Email { get; set; }
    public bool Active { get; set; }
    public DateTime CreatedAt { get; set; }
}

See Mapping to change table or column names, keys, and generated columns.

4. Query and write

var customers = db.Table<Customer>();
 
await customers.InsertAsync(new Customer { Name = "Ada", Active = true, CreatedAt = DateTime.UtcNow });
 
var active = await customers.Where(c => c.Active).OrderBy(c => c.Name).ToListAsync();
var count = await customers.Where(c => c.Email != null).CountAsync();
 
// Raw SQL when you need it; holes are parameters.
var domain = "example.com";
var rows = await db.QueryAsync<Customer>($"SELECT * FROM customer WHERE email LIKE {"%@" + domain}");

Next steps

PreviousIntroductionNext Interpolated SQL