Coder Legion - Recent posts tagged orm

Database Migrations in Rows ORM

Wed, 20 May 2026 06:11:36 +0000

Rows, the ORM built for Alusus language, takes a fundamentally different approach to database migrations compared to the linear, file-based systems found in tools like Sequelize, Flyway, or Rails ActiveRecord. Instead of maintaining an ordered sequence of migration files that must all be run in the right order, Rows ties migrations directly to your model definitions and tracks schema evolution on a per-table basis.

The Core Idea: Model Versions

Every model in Rows declares its current version as part of its @model annotation:

@model["vehicles", 2]
class Vehicle {
    define_model_essentials[];

    @notNull @primaryKey @Integer @column
    def id: int;

    @VarChar["50"] @column
    def name: String;

    @Integer @column["year"]
    def year: Int;

    @migration[1, 2]
    function migrate1To2(db: ref[Db]): SrdRef[Error] {
        return db.exec("alter table vehicles add column year integer").error;
    }
}

The number 2 in @model["vehicles", 2] is the current version of this model's schema. The @migration[1, 2] annotation on a method declares a function that upgrades the vehicles table from version 1 to version 2.

The library maintains a table_versions table in the database that records the current version of every table. When you call migrate(), the engine compares what versions the DB currently has against what versions the models declare, and figures out exactly which migration functions need to run.

The Migration Lifecycle

Step by step

Ensure tracking table exists. The engine creates the table_versions table if it is not already there.
Read current state. It queries table_versions to get the current version number for each table that has been migrated before.
Pick needed migrations. For each model, the engine walks the version chain starting from the current DB version up to the model's target version, collecting every migration function needed. If any step in the chain is missing a migration function, it returns an error immediately.
Populate dependencies. Each migration function can declare that it depends on another table being at a certain version. The engine resolves these into direct migration-to-migration dependencies.
Topological sort. The collected migrations are sorted using Kahn's algorithm so that every migration runs only after all of its dependencies have completed. If a dependency cycle is detected, an error is returned.
Run and record. Each migration is executed in sorted order. After each one succeeds, table_versions is updated to record the new version for that table.

Fresh Databases: No Migrations Needed

When a table does not yet exist in the database (version 0), the engine does not require you to write a migration function. It automatically generates a CREATE TABLE statement directly from the model's field definitions and annotations.

This means for a brand-new development environment you just call migrate() and all tables are created from scratch — no migration functions required at all. Migration functions are only needed when you need to transform an existing table from one version to another.

Multi-Step Migrations

A model can hold multiple migration functions, each covering a different version step. The engine automatically chains them together:

@model["vehicles", 4]
class Vehicle {
    // ... current field definitions ...

    @migration[2, 3, { Price: 1 }]
    function migrate2To3(db: ref[Db]): SrdRef[Error] {
        return db.exec("insert into prices select id as price_id, the_price as price from vehicles").error;
    }

    @migration[3, 4]
    function migrate3To4(db: ref[Db]): SrdRef[Error] {
        return db.exec("alter table vehicles drop column the_price").error;
    }
}

If a database is currently at version 2, the engine will run migrate2To3 and then migrate3To4 in sequence, leaving the table at version 4. If it is already at version 3, only migrate3To4 runs. A jump from version 1 to version 4 would chain migrate1To2 (from the now-deleted or earlier version of the model) through each step.

Cross-Table Dependencies

The third argument to @migration declares which other tables — and at which version — must be ready before this migration can run. The engine uses these declarations to determine a safe execution order across all tables.

@migration[2, 3, { Price: 1 }]
function migrate2To3(db: ref[Db]): SrdRef[Error] {
    // This migration copies data from vehicles into the prices table.
    // It must only run after the prices table exists at version 1.
    return db.exec("insert into prices select id as price_id, the_price as price from vehicles").error;
}

The dependency { Price: 1 } tells the engine: "before running this function, make sure the prices table is at version 1." The engine resolves this into a direct ordering constraint between the two migrations and uses the topological sort to enforce it.

Bypassing Auto Table Generation

By default the engine creates a table automatically for any model whose table does not yet exist. If you need full control over the initial table creation for whatever reason you can define a migration from version 0 yourself. The presence of a @migration[0, N] function signals to the engine to skip the auto-generation entirely and use your function instead:

@model["vehicles", 1]
class Vehicle {
    // ... field definitions ...

    @migration[0, 1]
    function createTable(db: ref[Db]): SrdRef[Error] {
        return db.exec(
            "create table vehicles (id integer primary key, name varchar(50)) partition by range (id)"
        ).error;
    }
}

Arbitrary Migrations using Fake Models

Sometimes you need to run a one-off data migration that does not correspond to a structural change in any particular table. You can use a "fake" model — a class with no column definitions — purely as a container for a migration function:

@model["price_update", 1]
class PriceUpdate {
    @migration[0, 1, { Vehicle: 2 }]
    function migrate0To1(db: ref[Db]): SrdRef[Error] {
        return db.exec("update vehicles set the_price = the_price + 50").error;
    }
}

Because this model has a @migration[0, 1] function, no table is created for it. The engine just runs the function and records price_update at version 1 in table_versions. The dependency { Vehicle: 2 } ensures the vehicles table is at the expected state before the data update runs.

Running Migrations

You pass a schema — a single model or a grouped set of models — to schemaBuilder and call migrate():

// Single model
def schema: Vehicle;
db.schemaBuilder[schema].migrate();

// Multiple models
def schema: { Vehicle, Price, PriceUpdate };
db.schemaBuilder[schema].migrate();

The engine handles everything: determining what needs to run, ordering it correctly, and recording progress.

Cleaning Up Old Migrations

Once a migration function has been deployed and run in production, it can be deleted from the source code. The engine only needs migration functions that bridge the gap between the current DB version and the target version. Any migration that covers a version range already passed in production is simply never consulted again.

This is a significant ergonomic improvement: over time your model files stay lean rather than accumulating an ever-growing list of historical migration methods.

Comparison with Linear Migration Systems

Tools like Sequelize, Flyway, and Rails ActiveRecord manage migrations as a linearly ordered sequence of numbered files. Every migration ever written must be present and run in order, even on a fresh database.

Concern	Linear system	Rows
New table	Migration needed	Auto generated, no migration needed
Understanding current schema	Must mentally replay all migrations	Read the model definition directly
Fresh database	Run every migration from the beginning	Auto-generate tables from models
Branch conflicts	Two people adding migrations get sequence number conflicts	Each model is independent; different models never conflict
Cleaning up history	Squashing migrations is risky and non-trivial	Delete functions once they are deployed; no risk
Cross-table ordering	Implicit via file numbering; easy to get wrong	Explicit dependency declarations; engine enforces correct order
Arbitrary data migrations	A migration file like any other	Fake model with a 0→1 migration function
Schema as documentation	Migration files are authoritative, model may drift	Model is always authoritative and up to date

Branch conflicts

In a linear system, two developers working on different features each create the next migration file. One calls it 0042_add_tags.sql and the other calls it 0042_add_ratings.sql. When the branches merge, one of them must be renumbered and every developer must re-run migrations. In Rows, because migrations belong to their model and are identified by version pairs rather than global sequence numbers, two developers working on Article and Comment respectively can never conflict with each other.

Schema clarity

With a linear system, the only way to know the current shape of a table is to read every migration that has ever touched it. In Rows, the model class is always the authoritative description of the current schema. Columns, types, nullability, defaults, primary keys, and foreign keys are all declared there. The migration functions are only concerned with the delta between versions, not the full picture.

History hygiene

Linear systems accumulate migrations indefinitely. Squashing them into a single "initial" migration is possible but fragile and infrequently done. In Rows, migration functions for old version ranges can simply be deleted once they have been run in production. The model definition already captures the end state; there is nothing to preserve.

Filtering, sorting, and pagination with the fluent query builder

Mon, 20 Apr 2026 12:51:41 +0000

So far in this series we have mapped entities, validated them, and performed basic CRUD. But real applications rarely load all records from a table. You need to search, filter, sort, and paginate.

Trysil provides a fluent API for this: TTFilterBuilder<T>. You chain method calls to build a filter, then pass it to Select<T>. The builder generates parameterized SQL behind the scenes — no string concatenation, no injection risk.

Basic filtering

uses
  Trysil.Filter;

var
  LBuilder: TTFilterBuilder<TTContact>;
  LFilter: TTFilter;
  LContacts: TTList<TTContact>;
begin
  LContacts := TTList<TTContact>.Create;
  try
    LBuilder := LContext.CreateFilterBuilder<TTContact>();
    try
      LFilter := LBuilder
        .Where('Lastname').Equal('Smith')
        .Build;

      LContext.Select<TTContact>(LContacts, LFilter);
    finally
      LBuilder.Free;
    end;

    for LContact in LContacts do
      WriteLn(Format('%s %s', [LContact.Firstname, LContact.Lastname]));
  finally
    LContacts.Free;
  end;
end;

The flow is always the same:

Create a builder with LContext.CreateFilterBuilder<T>
Chain conditions with .Where, .AndWhere, .OrWhere
Apply an operator (.Equal, .Like, .Greater, etc.)
Call .Build to get a TTFilter
Pass the filter to LContext.Select<T>

Available operators

Method	SQL
`.Equal(value)`	`= :param`
`.NotEqual(value)`	`<> :param`
`.Greater(value)`	`> :param`
`.GreaterOrEqual(value)`	`>= :param`
`.Less(value)`	`< :param`
`.LessOrEqual(value)`	`<= :param`
`.Like(pattern)`	`LIKE :param`
`.NotLike(pattern)`	`NOT LIKE :param`
`.IsNull`	`IS NULL`
`.IsNotNull`	`IS NOT NULL`

Combining conditions

Use .AndWhere and .OrWhere to combine multiple conditions:

LFilter := LBuilder
  .Where('Lastname').Equal('Smith')
  .AndWhere('Email').IsNotNull
  .Build;

LFilter := LBuilder
  .Where('City').Equal('Rome')
  .OrWhere('City').Equal('Milan')
  .Build;

Pattern matching with LIKE

LFilter := LBuilder
  .Where('Lastname').Like('Sm%')
  .Build;

Standard SQL wildcards apply: % matches any sequence of characters, _ matches a single character.

Sorting

LFilter := LBuilder
  .Where('Country').Equal('Italy')
  .OrderByAsc('Lastname')
  .Build;

You can chain multiple sort clauses:

LFilter := LBuilder
  .Where('Country').Equal('Italy')
  .OrderByAsc('Lastname')
  .OrderByAsc('Firstname')
  .Build;

For descending order, use .OrderByDesc:

LFilter := LBuilder
  .OrderByDesc('Price')
  .Build;

Note: you can sort without filtering — just skip the .Where call.

Pagination

For large datasets, load data in pages:

const
  PageSize = 20;
var
  LPage: Integer;
begin
  LPage := 3; // zero-based page index

  LFilter := LBuilder
    .OrderByAsc('Lastname')
    .Limit(PageSize)
    .Offset(LPage * PageSize)
    .Build;

  LContext.Select<TTContact>(LContacts, LFilter);
end;

.Limit(n) sets the maximum number of rows to return. .Offset(n) skips the first n rows. Combined with sorting, this gives you clean, predictable pagination.

Counting records

Sometimes you need the total count (for example, to display "Page 3 of 12"):

var
  LCount: Integer;
begin
  LFilter := LBuilder
    .Where('Country').Equal('Italy')
    .Build;

  LCount := LContext.SelectCount<TTContact>(LFilter);
end;

SelectCount<T> returns the number of matching rows without loading the entities into memory.

A complete example

Here is a realistic search function that combines filtering, sorting, pagination, and counting:

procedure TContactService.Search(
  const ASearchText: String;
  const APage: Integer;
  const APageSize: Integer;
  const AContacts: TTList<TTContact>;
  out ATotalCount: Integer);
var
  LBuilder: TTFilterBuilder<TTContact>;
  LFilter: TTFilter;
begin
  LBuilder := FContext.CreateFilterBuilder<TTContact>();
  try
    if not ASearchText.IsEmpty then
      LBuilder
        .Where('Lastname').Like(Format('%s%%', [ASearchText]))
        .OrWhere('Firstname').Like(Format('%s%%', [ASearchText]));

    LBuilder
      .OrderByAsc('Lastname')
      .OrderByAsc('Firstname');

    LFilter := LBuilder.Build;
    ATotalCount := FContext.SelectCount<TTContact>(LFilter);

    LBuilder
      .Limit(APageSize)
      .Offset(APage * APageSize);

    LFilter := LBuilder.Build;
    FContext.Select<TTContact>(AContacts, LFilter);
  finally
    LBuilder.Free;
  end;
end;

What is next

We can now search, sort, and paginate our data with a clean fluent API. In the next article we will tackle relations and lazy loading — how to model parent-child relationships and load related entities on demand.

Trysil is open-source and available on GitHub. Stars and feedback are always appreciated!

Meet Trysil: a lightweight ORM for Delphi

Mon, 20 Apr 2026 12:51:09 +0000

If you have ever written a Delphi application that talks to a database, you know the routine: write SQL by hand, manage parameters, loop through datasets, and copy values into objects field by field. It works, but it is tedious and error-prone.

Trysil is an open-source ORM for Delphi that eliminates that boilerplate. You decorate your classes with attributes, and the framework handles the rest — mapping, querying, inserting, updating, deleting. It is lightweight, attribute-driven, and built on top of FireDAC, so it works with SQLite, PostgreSQL, SQL Server, and Firebird out of the box.

In this first article we will go from zero to a working CRUD application with SQLite.

Installation

You can install Trysil in three ways:

GetIt — search for "Trysil" in the Embarcadero GetIt Package Manager
Boss — boss install davidlastrucci/Trysil
Manual — clone the GitHub repo, open Packages/<ver>/Trysil.groupproj, and build all

After installation, point your project's Search Path to the compiled output directory.

Your first entity

An entity in Trysil is a plain Delphi class with attributes. No base class to inherit, no interface to implement.

unit Contact.Model;

{$WARN UNKNOWN_CUSTOM_ATTRIBUTE ERROR}

interface

uses
  Trysil.Types,
  Trysil.Attributes,
  Trysil.Validation.Attributes;

type
  [TTable('Contacts')]
  [TSequence('ContactsID')]
  TTContact = class
  strict private
    [TPrimaryKey]
    [TColumn('ID')]
    FID: TTPrimaryKey;

    [TRequired]
    [TMaxLength(50)]
    [TColumn('Firstname')]
    FFirstname: String;

    [TRequired]
    [TMaxLength(50)]
    [TColumn('Lastname')]
    FLastname: String;

    [TMaxLength(255)]
    [TEmail]
    [TColumn('Email')]
    FEmail: String;

    [TColumn('VersionID')]
    [TVersionColumn]
    FVersionID: TTVersion;
  public
    property ID: TTPrimaryKey read FID;
    property Firstname: String read FFirstname write FFirstname;
    property Lastname: String read FLastname write FLastname;
    property Email: String read FEmail write FEmail;
    property VersionID: TTVersion read FVersionID;
  end;

A few things to note:

[TTable('Contacts')] maps the class to the Contacts table.
[TSequence('ContactsID')] tells Trysil how the primary key is generated.
[TPrimaryKey] and [TColumn('...')] mark the primary key and map each field to a column.
[TVersionColumn] enables optimistic locking — Trysil will check this value on every update to prevent lost writes.
[TRequired], [TMaxLength], [TEmail] are validation attributes — we will cover them in depth in a later article.
{$WARN UNKNOWN_CUSTOM_ATTRIBUTE ERROR} turns typos in attribute names into compile-time errors. Always add this.

Fields are strict private with public properties. The ORM accesses them through RTTI.

Connecting to SQLite

uses
  Trysil.Data,
  Trysil.Data.FireDAC.SQLite,
  Trysil.Data.FireDAC.ConnectionPool,
  Trysil.Context;

var
  LConnection: TTConnection;
  LContext: TTContext;
begin
  // Disable connection pooling (not needed for desktop apps)
  TTFireDACConnectionPool.Instance.Config.Enabled := False;

  // Register and create the connection
  TTSQLiteConnection.RegisterConnection('MyApp', 'contacts.db');
  LConnection := TTSQLiteConnection.Create('MyApp');
  try
    LContext := TTContext.Create(LConnection);
    try
      // ... use the context
    finally
      LContext.Free;
    end;
  finally
    LConnection.Free;
  end;
end;

TTContext is the single entry point for all ORM operations. You create it with a connection, and it gives you methods for reading, writing, and querying entities.

CRUD operations

Create

var
  LContact: TTContact;
begin
  LContact := LContext.CreateEntity<TTContact>();
  LContact.Firstname := 'Ada';
  LContact.Lastname := 'Lovelace';
  LContact.Email := '*Emails are not allowed*';
  LContext.Insert<TTContact>(LContact);
end;

Always use CreateEntity<T> to create new entities — it initializes internal state that the context needs to track the object.

Read

var
  LContacts: TTList<TTContact>;
begin
  LContacts := TTList<TTContact>.Create;
  try
    // Load all contacts
    LContext.SelectAll<TTContact>(LContacts);

    for LContact in LContacts do
      WriteLn(Format('%s %s — %s', [
        LContact.Firstname,
        LContact.Lastname,
        LContact.Email]));
  finally
    LContacts.Free;
  end;
end;

To fetch a single entity by ID:

var
  LContact: TTContact;
begin
  LContact := LContext.Get<TTContact>(42);
  // raises an exception if not found
end;

Update

LContact.Email := '*Emails are not allowed*';
LContext.Update<TTContact>(LContact);

Behind the scenes, Trysil generates an UPDATE statement that includes the VersionID in the WHERE clause. If another user has modified the same record in the meantime, the update fails with a concurrency error rather than silently overwriting their changes.

Delete

LContext.Delete<TTContact>(LContact);

The SQL table

For completeness, here is the SQLite schema that matches our entity:

CREATE TABLE Contacts (
  ID INTEGER PRIMARY KEY,
  Firstname TEXT NOT NULL,
  Lastname TEXT NOT NULL,
  Email TEXT,
  VersionID INTEGER NOT NULL DEFAULT 1
);

What is next

In this article we defined an entity, connected to SQLite, and performed full CRUD — all without writing a single line of SQL.

In the next article we will look deeper into entity mapping: nullable fields, custom types, and how Trysil handles the relationship between your Delphi classes and your database schema.

The full source code is available on GitHub.

Trysil is an open-source project. If you find it useful, consider giving it a star on GitHub!

Why learning to build your own ORM is worth it (even if you use EF Core or Dapper)

Fri, 19 Dec 2025 13:53:30 +0000

Why learning to build your own ORM is worth it (even if you use EF Core or Dapper)

Most developers meet ORMs the same way they meet electricity, you flip a switch and things work. That’s great, until something gets slow, a query behaves oddly, or you hit a transaction or concurrency edge case and you suddenly need to know what’s happening under the hood.

Building a small ORM, even a deliberately limited one, is one of the fastest ways to close the gap between “I can use EF Core or Dapper” and “I understand data access.”

To keep it grounded, I’ll anchor this around my tiny demo ORM (MicroOrm), a .NET 8 sample using SQLite, simple POCOs, a lightweight Include for eager loading, and CancellationToken propagation end to end. (GitHub)

1) You stop treating the database like a black box

When you write mapping yourself, you’re forced to answer questions full ORMs often hide:

What SQL is actually executed?
How are parameters created and bound?
How do nulls map into value types vs nullable types?
What happens when schema changes, column names drift, or types don’t match?
How do you retrieve identities safely after inserts?

This is where “I know EF” turns into “I can debug a data issue under pressure.”

2) Reflection becomes a tool, not a mystery

A tiny ORM almost always starts with reflection.

You inspect a type, find its attributes, discover the key property, build a column list, and map rows back into objects. In MicroOrm’s demo, entities like Blog and Post use familiar attributes like [Table], [Key], [ForeignKey], and [InverseProperty], which is exactly the kind of metadata you typically read via reflection. (GitHub)

The payoff is immediate because you hit two truths fast:

Reflection is powerful, it removes a ton of repetitive glue code.
Reflection is not free, so you learn to cache metadata and keep reflection out of hot paths.

Those instincts carry straight into EF Core too.

3) Generics give you type safety and a clean API surface

Generics are the other superpower of a micro ORM.

They let you write APIs that feel natural in C# and stay strongly typed:

GetById<T>(id) returns a T, not object
GetAll<T>() returns List<T>, not dictionaries
One set of operations can work across your entities without repetition

In practice, building a micro ORM becomes a “generics + reflection” exercise done right, compile-time safety on the outside, runtime discovery on the inside.

4) You finally learn ADO.NET for real (SqlConnection, SqlCommand, and friends)

EF Core and Dapper sit on top of ADO.NET. When you build your own ORM, you stop skipping the fundamentals:

Connections (SqlConnection, SqliteConnection, or DbConnection)
You learn what “open late, close early” actually looks like, why using or await using matters, and how connection pooling changes the way you should think about lifetime.
Commands (SqlCommand, DbCommand)
You get comfortable with parameterized queries (and why they’re non negotiable), command timeouts, and how provider differences show up.
Readers (DbDataReader)
You learn what streaming results means, how mapping happens row by row, and where conversions and null handling can bite you.
Transactions (DbTransaction)
You start treating transaction boundaries as a deliberate design choice, not an incidental side effect of the ORM.

MicroOrm’s demo explicitly highlights cancellation support across opening connections and executing commands, which is exactly the sort of detail you only appreciate once you’re directly using these classes. (GitHub)

5) You learn the real price of convenience (and why loading strategy matters)

MicroOrm’s Include supports both references and collections, implemented as extra queries per entity. It’s intentionally simple, and extremely educational because you can feel the tradeoff immediately: clearer code and predictable behavior, plus a very real risk of N+1 query explosions if you’re not careful. (GitHub)

After you build even a basic Include, you start spotting inefficient loading patterns everywhere, including in mature ORMs.

6) You learn portability the honest way

“Database agnostic” always has seams.

The sample calls it out plainly: switching from SQLite to SQL Server means swapping the provider and adjusting identity retrieval in SqlBuilder.Insert to use SELECT SCOPE_IDENTITY();. That single detail teaches a big lesson, database behavior differences are real and they show up fast. (GitHub)

The takeaway

Writing a tiny ORM is not about shipping a competitor to EF Core.

It’s about gaining X-ray vision for what’s underneath, reflection, generics, ADO.NET primitives like SqlConnection and SqlCommand, query cost, round trips, and transactions. Then, when you choose EF Core or Dapper, you’re not just using them, you’re using them with intent.