Docs
Kiwi ORM
Version Current

Quickstart

Quickstart

Define an entity and a context, connect to a database, and run your first Entity and Raw SQL queries.

ORM Current 3 min read Updated

Prerequisites

  • A .NET project, and access to the Kiwi ORM packages from Kiwify Labs
  • A database from the supported list, and its ADO.NET driver

Tip

Included in the free, source-available edition. See Editions and features.

1. Add Kiwi ORM#

Reference the Kiwi ORM Core assemblies (Kiwify.Kiwi.ORM.Core and Kiwify.Kiwi.ORM.Abstractions) and the ADO.NET driver for your database. How you obtain the packages depends on your licence. See Packages and assemblies.

2. Describe a table as an entity#

An entity derives from Entity<T>, names its table with [TableInfo], and maps each column with [ColumnInfo]. Properties call SetAndNotify, which is how change tracking works.

csharp
using Kiwify.Kiwi.ORM.Abstractions.Attributes.Table;
using Kiwify.Kiwi.ORM.Core;
using Kiwify.Kiwi.ORM.Core.DbObjects;

[DbContextObject("Sales")]
[TableInfo("customers")]
public class Customer : Entity<Customer>
{
    private int _customerId;
    private string _name = "";
    private string _city = "";
    private bool _isActive;

    [ColumnInfo("customerid", IsPrimaryKey = true, IsAutoIncrement = true)]
    public int CustomerId { get => _customerId; set => SetAndNotify(ref _customerId, value); }

    [ColumnInfo("name")]
    public string Name { get => _name; set => SetAndNotify(ref _name, value); }

    [ColumnInfo("city")]
    public string City { get => _city; set => SetAndNotify(ref _city, value); }

    [ColumnInfo("isactive")]
    public bool IsActive { get => _isActive; set => SetAndNotify(ref _isActive, value); }
}

You rarely type this by hand: the tooling can generate it from your database. See Generate entities and migrations.

3. Define a context#

A context groups the entities that belong together. [DbContextObject("Sales")] on the entity ties it to the matching AddDbObjects("Sales"):

csharp
using Kiwify.Kiwi.ORM.Core.Context;

public class SalesContext : DatabaseContext
{
    protected override void RegisterDbObjects() => AddDbObjects("Sales");
}

4. Connect#

Tell the context which database it is talking to. This is the only provider-specific line in your data-access code:

csharp
using var db = DatabaseContext
    .CreateContext<SalesContext>(i => i.UsePostgreSql(connectionString))
    .Connect();

Use the matching Use... helper for your engine (for example UseSqlServer, UseMySql, UseMariaDb, UseFirebird, UseSQLite), or i.Configure<SqlServerDatabaseSpecification>(connectionString). See Supported databases.

5. Query with Entity mode#

csharp
using Kiwify.Kiwi.ORM.Core.Context.Extensions;

var customers = db.Select<Customer>()
    .Where(c => c.City == "London" && c.IsActive)
    .OrderBy(c => c.CustomerId)
    .Execute();

Conditions are C# expressions, checked by the compiler and safe to refactor. Use ExecuteAsync() for the async form.

6. Query with Raw SQL (KMQL)#

csharp
using Kiwify.Kiwi.ORM.Core.Helper;

var rows = await db.ExecuteReadAsync<CustomerRow>(
    "SELECT {{C: CustomerId, Name}} FROM {{T: customers}} WHERE {{C: City}} = @city",
    new { city = "London" });

{{T: ...}} and {{C: ...}} quote tables and columns correctly for whichever database you are connected to. Rows are mapped to the plain class CustomerRow. See Raw SQL with KMQL.

Next steps#

Expected result

  • A typed query returns rows from your database in both Entity and Raw SQL mode