UQL | Blog

What does an ORM really cost you?

Sun, 09 Aug 2026 00:00:00 GMT

My bench now does real stuff, full PostgreSQL round-trip operations.

Six ORMs, one real PostgreSQL, and a full lifecycle per pass: insert 10 rows, read 200 back with a filter and a sort, update one, read it again, load 50 parents with their children, delete, read the empty table. Every step timed separately, median of 250 interleaved iterations.

The results

Entry	Adds	Total
UQL	+232µs	1,621µs
Drizzle	+685µs	2,074µs
TypeORM	+838µs	2,227µs
Sequelize	+1,185µs	2,574µs
Prisma	+1,345µs	2,734µs
MikroORM	+2,236µs	3,625µs

Adds is the number that matters, and it is the whole reason this benchmark works. Every entry pays the same PostgreSQL bill, so the totals compress into a 2.2x range and every ORM looks about the same. Subtract the floor, which is hand-written SQL with the rows mapped by hand at 1,389µs, and what is left is the ORM’s own contribution. That spans nearly 9.6x.

Everything above runs on node-postgres, so the driver is not the variable. Four of the six support nothing else.

Prisma

Prisma is not slow across the board, and it does not finish last; it was MikroORM at 3,625µs against Prisma’s 2,734µs. Prisma’s nested read, the hardest step in the set, is the second fastest of any ORM here at 440µs. Its update, delete and single-row reads are all mid-field.

It is one step:

INSERT 10 rows
raw pg (hand-written)	454µs
UQL	488µs
MikroORM	625µs
Drizzle	635µs
Sequelize	643µs
TypeORM	668µs
Prisma	1,366µs

That one step is 2.0x the next slowest ORM and it is most of why Prisma places fifth. Turning on its query log shows what it sends:

What Prisma sends for createManyAndReturn

INSERT INTO "public"."User" ("name","email","companyId") VALUES ($1,$2,$3), ($4,$5,$6), ...
COMMIT

So createManyAndReturn wraps the batch in an explicit transaction, where the other five send one statement and stop. That is a fair thing to do and it is not the explanation: a BEGIN/COMMIT pair on this machine costs 88µs, and the gap to TypeORM, the next slowest here, is 698µs. The transaction is about an eighth of it. The rest is Prisma’s own overhead on the way in and out, which is the part you cannot opt out of.

Prisma 7 dropped its Rust query engine, and the client runtime is now TypeScript. This is the faster Prisma, not the old one.

The nested read is where ORMs are actually decided

It is the only step that loads a relation, and it has the widest spread of any read:

SELECT 50 parents with their children
raw pg (hand-written)	256µs
UQL	346µs
Prisma	440µs
TypeORM	498µs
Drizzle	535µs
Sequelize	680µs
MikroORM	1,205µs

This is the step worth caring about, because it is the one an ORM exists to do. Anyone can send an INSERT. Turning two result sets into an object graph without an N+1 is the actual job, and the field spans 3.5x on it.

Run it yourself

git clone https://github.com/rogerpadilla/ts-orm-benchmark.git
cd ts-orm-benchmark
bun install

DATABASE_URL=postgres:///postgres npm run bench

It creates its own database and rewrites its own result tables, so the published numbers cannot drift from the last run. CI runs the full lifecycle with assertions on every push.

The latest set always lives on the benchmark page, and there is a feature-by-feature ORM comparison if speed is not your only axis. If your numbers come out different, open an issue.

Zero dependencies: what we deleted

Sun, 02 Aug 2026 00:00:00 GMT

UQL is a dependency-free TypeScript ORM for PostgreSQL, MySQL, MariaDB, SQLite and MongoDB.

npm i uql-orm installs one package. No dependencies, every dialect included.

A month ago it had four mandatory packages, roughly 4 MBs unpacked; now it is 992 KB unpacked.

One release, four dependencies gone

0.21.0 did it in one pass: ~4.0 MB down to 992 KB, cold start from 16.9 ms to 8.9 ms. Four packages, one job each, none worth a dependency of its own.

tslib existed so TypeScript’s helper functions didn’t repeat across files. "importHelpers": false costs a few hundred bytes per file instead of a dependency edge.

sqlstring escaped MySQL and MariaDB literals, badly: a Uint8Array came out as `0` = 255 instead of X'ff00', a plain object as '[object Object]'. No crash, no warning, just wrong output that looks fine until it isn’t. Dialect.escape handles all three SQL dialects itself now, byte-for-byte identical across 29 value shapes, and those two cases throw instead of writing garbage.

reflect-metadata (264 KB) earned its keep with one call, Reflect.getMetadata('design:type', ...), so @Field() could guess a column’s type from the property. Optional as of this release, gone two releases later.

jiti (1.8 MB), a full TypeScript transpiler, existed to read one file: uql.config.ts. That’s a lot of compiler to hire for one sticky note. Also gone; that config now needs a runtime that already speaks TypeScript (bun, or node --import tsx).

Then the stuff that was never code: 369 sourcemaps nobody opened, and a 108 KB CHANGELOG, shipped in every install anyway. files in package.json is ["dist", "README.md"] now.

Then reflection went too

Two releases later, reflect-metadata stopped being optional and started being pointless. 0.23.0 moved decorators to the TC39 standard spec: @Field() and @Id() require an explicit type now, checked against the property, so there’s nothing left to reflect. The full story, including what it cost, is in Standard decorators: props & cons.

What one `npm i` puts on disk

Install one package into an empty project and count the bytes yourself:

npm i --omit=dev uql-orm
find node_modules -type f -exec cat {} + | wc -c

Unpacked bytes on disk, not the 288 kB you download. Tarballs compress; cold starts don’t care.

Package	Installed	Files
`uql-orm` 0.24.1	1.0 MB	384
`@mikro-orm/postgresql` 7.1.9	4.7 MB	1,153
`drizzle-orm` 0.45.2	9.9 MB	2,667
`sequelize` 6.37.8	15.0 MB	2,708
`typeorm` 1.1.0	22.5 MB	3,663
`@prisma/client` 7.9.1	75.0 MB	94

One thing to hold against this table before you screenshot it: 93% of @prisma/client is 70 MB of Rust query compilers cross-compiled to WebAssembly, one per engine it supports, which is either an engineering marvel or a cry for help. UQL ships every dialect too, so that part isn’t a fair hit on Prisma. Per dialect it’s actually smaller: 4.9 MB for its Postgres compiler alone against 19.9 kB gzipped for UQL’s entire Postgres entry point.

No row includes a driver. Add pg to any of them and they all grow the same amount. This table is the floor.

What the small number doesn’t cover

UQL is the small number here, your driver isn’t. pg, mysql2, mariadb, mongodb and better-sqlite3 all have their own weight, and the last one needs a native build. UQL’s promise is narrower than “small”: it adds nothing on top of whichever one you already picked.

Every entry point has a gzip budget checked on every build, because 0.13.0 once let node:async_hooks leak into browser bundles and had to be pulled. Lesson learned, budget added.

Get started

npm i uql-orm

If your install contains something that shouldn’t be there, open an issue.

Standard decorators: props & cons

Sat, 01 Aug 2026 00:00:00 GMT

UQL is a dependency-free TypeScript ORM for PostgreSQL, MySQL, MariaDB, SQLite and MongoDB.

UQL 0.23 moved its decorators to the TC39 standard spec. experimentalDecorators and emitDecoratorMetadata are gone, reflect-metadata is gone, and one thing became possible that was not possible before.

It also deleted three decorators, removed parameter injection, and locked NestJS out of the decorator API entirely. Migration posts usually stop at the wins. This is the whole ledger.

What it looks like

Before: legacy decorators

import { Entity, Field, Id, ManyToOne } from 'uql-orm';

import 'reflect-metadata';

@Entity()
class User {
  @Id()
  id?: number;

  @Field()
  name?: string;

  @ManyToOne()
  company?: Relation<Company>;
}

After: the standard spec

@Entity()
class User {
  @Id({ type: Number })
  id?: number;

  @Field({ type: String })
  name?: string;

  @ManyToOne({ entity: () => Company })
  company?: Company;
}

More typing. type on every field, entity on every relation, because nothing reflects any more. That looks like a pure loss until you notice what the compiler can now do with it.

The type you declare is checked against the property

This is the part worth the migration.

Under the legacy spec, a property decorator has this shape:

type PropertyDecorator = (target: Object, propertyKey: string | symbol) => void;

There is no type parameter carrying the property’s type. The decorator is handed a key and nothing else, so the options you pass it are just data. Write this and it compiled fine:

@Field({ type: String })
age?: number;

You got a TEXT column for a number, and you found out when the data looked wrong. emitDecoratorMetadata did not save you, because an explicit type skipped inference entirely:

the old definition.ts

if (opts.type) {
  opts = { ...opts, typeInferred: false };
} else {
  opts = { ...opts, type: inferType(entity, key), typeInferred: true };
}

Reflection was the fallback, not the check. The moment you stated a type, the one thing that knew the real type stopped looking.

The standard spec hands a field decorator a ClassFieldDecoratorContext<This, Value>, which is generic in the field’s value type. That single difference is the whole story, because now a decorator can constrain what it may be attached to:

packages/uql-orm/src/entity/decorator/members.ts

/** A member decorator that also constrains the property it may be applied to. */
type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext<unknown, V>) => void;

/** A declared `type` wins; otherwise the column is the referenced primary key's own type. */
type DeclaredValue<O> = O extends { readonly type: infer T extends FieldType }
  ? TsTypeOf<T>
  : O extends { readonly references: EntityGetter<infer E> }
    ? IdValue<E>
    : never;

export function Field<O extends FieldOptions<DeclaredValue<O>> & ({ type: FieldType } | { references: EntityGetter })>(
  opts: O,
): MemberDecorator<DeclaredValue<O> | undefined>;

@Field({ type: String }) returns a decorator that only applies to string | undefined. Put it on a number and it does not compile. The mandatory type stopped being redundant typing and became a claim the compiler checks.

Once one option can name the value a property holds, the others have to agree with it:

import { OneToMany } from 'uql-orm';

@ManyToOne({ entity: () => Company })
supplier?: Vendor;        // error: entity and property disagree

@OneToMany({ entity: () => Item })
items?: Item;             // error: a to-many cardinality needs an array

@Field({ type: 'int' })
createdAt?: Date;         // error: a Date field is not an integer column

@Field({ references: () => User })
authorId?: number;        // error: User's key is a uuid, so this column is a string

@Id({ type: 'uuid', onInsert: () => 42 })
id?: string;              // error: a uuid column is not stamped with a number

None of these were catchable before. They are not new bugs the migration introduced, they are old bugs it made visible. A type-test suite pins every one of them and fails the build if any stops erroring, and all but the foreign key survive being reached through the imperative defineEntity too.

The last two arrived later, in 0.24.3. Same mechanism, applied to the two other things that decide what a column holds: the key a foreign key points at, and the generator that stamps a value into it.

What reflection was costing

reflect-metadata was 264 KB, carried for one call: Reflect.getMetadata('design:type', ...). It also required every consumer to import it once, globally, before any entity loaded, and to remember to keep two compiler flags on.

It bought less than it looked like. Reflected types could not survive a circular import, which is why Relation<T> existed at all: an alias whose only job was to break a cycle that reflection itself created. It is deleted now.

Dropping it is part of why the package installs 1 MB with no dependencies.

What we gave up

The honest column.

@InjectQuerier() is gone. The standard spec has no parameter decorators, and the TC39 proposal for them is still Stage 1. A @Transactional() method now reads its querier from AsyncLocalStorage:

import { Transactional, currentQuerier } from 'uql-orm';

class UserService {
  @Transactional()
  async register(data: Partial<User>) {
    await currentQuerier().insertOne(User, data);
  }
}

@Log() and @Serialized() are gone. A standard-spec decorator cannot preserve a generic method’s signature, so both would have quietly widened the types of anything they wrapped. The useful half of @Log(), error enrichment, was moved into the querier itself.

NestJS projects cannot use UQL’s decorators at all. Nest injects constructor parameters with a parameter decorator, so a Nest project keeps experimentalDecorators: true, and one tsconfig.json cannot mix specs. This is not a temporary gap that closes when a proposal advances a stage. Those projects use defineEntity instead, which carries the same checks, bar the foreign key one.

target: 'esnext' is now forbidden. It is the one target where TypeScript emits decorator syntax untransformed, which Node and every browser reject with a SyntaxError. Every dated target downlevels it correctly.

declare fields stop working. The spec has nothing to decorate on a declare member, so narrowing an inherited relation needs a real field with an initializer.

Oxc, Vite 8’s default transformer, implements no decorators at all. It preserves @Entity() verbatim at every target, so a Vite 8 project needs esbuild, SWC or Babel through a plugin. esbuild, SWC, Babel with version: '2023-11', Bun and tsc all handle the spec.

Node 24 is the new minimum, shipped in the same release.

The two things that nearly broke it

Neither is in the spec documents, and both cost real time.

Symbol.metadata does not exist yet. No runtime we support defines it, checked on Node 24 and Bun 1.3. TypeScript’s decorator emit reads it to decide whether to build the metadata object at all, so without a polyfill every context.metadata is undefined and field registration is silently dropped rather than failing. UQL defines it with Symbol.for, not Symbol(), so a duplicated copy of the module under HMR or dual-loading lands on the same symbol, and so it agrees with the key esbuild and SWC fall back to.

tsc and SWC disagree about inheritance. tsc chains a subclass’s context.metadata to its parent’s. SWC does not, in any decorator version. Anything built on that prototype chain works under one compiler and quietly loses inherited fields under the other. UQL resolves inheritance by walking the class prototype chain instead, and there is a test that constructs the unchained shape SWC emits to prove it.

The codemod

uql-codemod does most of the mechanical work, reading types from the real type checker rather than guessing from the parse tree:

npx uql-codemod --project=tsconfig.json --dry-run
npx uql-codemod --project=tsconfig.json

It rewrites @Field/@Id types, relation entity getters, Relation<T> to T, @InjectQuerier() to currentQuerier(), and strips both flags from tsconfig.json while preserving your comments and formatting. It refuses to touch what it cannot be sure about: target: esnext, values inherited through extends, @Log() and @Serialized(), options objects it cannot read, and branded string ids.

tsc is the rest of the migration, and that is the point. The annotations the codemod inserts are checked against the properties they describe, so anything it got wrong is a compile error rather than a silently wrong column.

Was it worth it

Yes, and not because of the compiler flags.

Removing two tsconfig settings and a 264 KB polyfill is worth something, but it is housekeeping. The reason to do this was that reflection put the type in two places and let them drift, and no amount of care fixes a design where the compiler cannot see the mistake. Now there is one declaration and the compiler checks it against the property.

The bill was real: three decorators, parameter injection, and a framework’s worth of users pushed onto a different API. If you are on NestJS, this release cost you something and handed back a smaller install. That is a worse trade than everyone else got, and not one I can improve until TC39 moves.

Get started

npm i uql-orm
npx uql-codemod --project=tsconfig.json --dry-run

Upgrade guide
Entities: decorators and the imperative API
Zero dependencies: what we deleted to fit on the edge
How UQL compares
GitHub

If the codemod leaves something behind that it could have handled, open an issue with the entity that tripped it.

Semantic search: native vector similarity in a multi-dialect ORM

Thu, 12 Mar 2026 00:00:00 GMT

UQL is a dependency-free TypeScript ORM for PostgreSQL, MySQL, MariaDB, SQLite and MongoDB.

Most ORMs stop short of vector similarity. The moment you need it, you drop to raw SQL, hand-writing distance expressions and working around dialect quirks outside your type-safe query API.

UQL 0.3 adds native semantic search to the regular query API, including automatic index migration for HNSW and IVFFlat indexes.

What it looks like

You write

const results = await pool.findMany(Article, {
  $select: { id: true, title: true },
  $sort: { embedding: { $vector: queryEmbedding, $distance: 'cosine' } },
  $limit: 10,
});

UQL generates the right SQL for your database:

Generated SQL (PostgreSQL)

SELECT "id", "title" FROM "Article"
ORDER BY "embedding" <=> $1::vector
LIMIT 10

Generated SQL (MariaDB)

SELECT `id`, `title` FROM `Article`
ORDER BY VEC_DISTANCE_COSINE(`embedding`, ?)
LIMIT 10

Generated SQL (SQLite)

SELECT `id`, `title` FROM `Article`
ORDER BY vec_distance_cosine(`embedding`, ?)
LIMIT 10

The same query works on every dialect, with no raw SQL or dialect checks in your code.

For MongoDB, UQL translates the same query into an Atlas $vectorSearch pipeline. The Atlas search index itself has to be created in Atlas; see the reference for details.

MongoDB Atlas

[
  { "$vectorSearch": { "index": "embedding_index", "path": "embedding", "queryVector": ["..."], "numCandidates": 100, "limit": 10 } }
]

Entity setup

Define your vector field and index; UQL handles schema generation, extension creation, and index building:

import { Entity, Id, Field, Index } from 'uql-orm';

@Entity()
@Index(['embedding'], { type: 'hnsw', distance: 'cosine', m: 16, efConstruction: 64 })
export class Article {
  @Id({ type: Number }) id?: number;
  @Field({ type: String }) title?: string;

  @Field({ type: 'vector', dimensions: 1536 })
  embedding?: number[];
}

For Postgres, UQL automatically emits CREATE EXTENSION IF NOT EXISTS vector. MariaDB has vector support built in; SQLite requires loading the sqlite-vec extension.

Key features

Distance projection

Project the computed distance into your results with $project, without computing the distance twice:

import type { WithDistance } from 'uql-orm';

const results = (await pool.findMany(Article, {
  $select: { id: true, title: true },
  $sort: { embedding: { $vector: queryVec, $distance: 'cosine', $project: 'distance' } },
  $limit: 10,
})) as WithDistance<Article, 'distance'>[];

results[0].distance;

Annotate the result with the exported WithDistance<Article, 'distance'> helper to type the projected distance field.

4 distance metrics

Metric	Postgres	MariaDB	SQLite	MongoDB Atlas
`cosine`	`<=>`	✅	✅	✅ (index-defined)
`l2`	`<->`	✅	✅	✅ (index-defined)
`inner`	`<#>`	❌	❌	✅ (index-defined)
`l1`	`<+>`	❌	✅	❌

3 vector types

Type	Storage	Use Case
`'vector'`	32-bit float	Standard embeddings (OpenAI, etc.)
`'halfvec'`	16-bit float	50% storage savings, near-identical accuracy
`'sparsevec'`	Sparse	SPLADE, BM25-style sparse retrieval

halfvec and sparsevec are Postgres-only. MariaDB and SQLite transparently map them to their native VECTOR type, so your entities work everywhere.

Vector indexes

Type	Postgres	MariaDB	MongoDB Atlas
HNSW	✅ with `m`, `efConstruction`	❌	❌
IVFFlat	✅ with `lists`	❌	❌
Native	❌	✅ `VECTOR INDEX`	✅ `$vectorSearch`

Why `$sort`?

Vector similarity search is fundamentally sorting by distance. UQL reuses the existing $sort API, which composes naturally with $where, $select, $limit, and regular sort fields:

const results = await pool.findMany(Article, {
  $where: { category: 'science' },
  $sort: { embedding: { $vector: queryVec, $distance: 'cosine' }, title: 'asc' },
  $limit: 10,
});

Get started

npm i uql-orm

If you run into issues or missing features, open an issue on GitHub.

In search of the fastest TypeScript ORM

Tue, 10 Mar 2026 00:00:00 GMT

I kept seeing “just use Drizzle, it’s lightweight” and “ORMs are slow, use a query builder” repeated everywhere. So I decided to actually measure it.

The benchmark measures pure SQL generation speed: no database, no network, no connection pool. That isolates the overhead the ORM adds to every request. 7 entries, 8 query types, 3 runs averaged, on an Apple Silicon M4.

Methodology

Environment: Node.js v24.18.1, Apple M4 Pro, 3 runs averaged.
Versions: Latest stable of every entry as of August 2026 (TypeORM 1.1.0, MikroORM 7.1.9, Sequelize 6.37.8, Drizzle 0.45.2, Knex 3.3.0, Kysely 0.29.4, UQL 0.24.0).
Fairness: Each ORM uses its most idiomatic API (QueryBuilder for TypeORM/MikroORM), which benefits them by skipping entity overhead.
What’s measured: Pure SQL string generation, with no database, no I/O, and no connection pool. This isolates ORM overhead only.
Why no Prisma? Prisma’s query compiler is Rust compiled to WebAssembly rather than pure JS/TS, and it exposes no public SQL-compilation API, so it cannot be measured this way.

The results

INSERT: 10 rows in batch

Entry	ops/sec	vs winner
UQL	698K	1.00x
Knex	463K	0.66x
Sequelize	196K	0.28x
Kysely	189K	0.27x
MikroORM	111K	0.16x
TypeORM	42K	0.06x
Drizzle	12K	0.02x

UPDATE: SET + WHERE

Entry	ops/sec	vs winner
UQL	2,161K	1.00x
Kysely	796K	0.37x
Knex	695K	0.32x
TypeORM	282K	0.13x
Sequelize	236K	0.11x
MikroORM	218K	0.10x
Drizzle	79K	0.04x

UPSERT: ON CONFLICT by id

Entry	ops/sec	vs winner
UQL	691K	1.00x
Knex	433K	0.63x
Kysely	335K	0.48x
Sequelize	327K	0.47x
TypeORM	261K	0.38x
MikroORM	260K	0.38x
Drizzle	36K	0.05x

DELETE: simple WHERE

Entry	ops/sec	vs winner
UQL	3,996K	1.00x
Sequelize	1,361K	0.34x
Kysely	1,264K	0.32x
Knex	1,084K	0.27x
TypeORM	507K	0.13x
MikroORM	263K	0.07x
Drizzle	207K	0.05x

SELECT: 1 field

Entry	ops/sec	vs winner
UQL	4,675K	1.00x
Sequelize	3,084K	0.66x
Kysely	1,520K	0.33x
Knex	1,092K	0.23x
TypeORM	591K	0.13x
MikroORM	565K	0.12x
Drizzle	229K	0.05x

SELECT: WHERE + SORT + LIMIT

Entry	ops/sec	vs winner
UQL	1,365K	1.00x
Knex	614K	0.45x
Kysely	419K	0.31x
Sequelize	381K	0.28x
TypeORM	276K	0.20x
MikroORM	73K	0.05x
Drizzle	59K	0.04x

SELECT: complex $or + operators

Entry	ops/sec	vs winner
UQL	741K	1.00x
Knex	243K	0.33x
Kysely	216K	0.29x
TypeORM	158K	0.21x
Sequelize	150K	0.20x
Drizzle	34K	0.05x
MikroORM	28K	0.04x

AGGREGATE: GROUP BY + COUNT + HAVING

Entry	ops/sec	vs winner
UQL	1,482K	1.00x
Sequelize	416K	0.28x
Knex	304K	0.21x
TypeORM	277K	0.19x
Kysely	201K	0.14x
Drizzle	74K	0.05x
MikroORM	69K	0.05x

Interactive charts →

Three things that surprised me

1. The “lightweight” option is the slowest thing in the benchmark.

Drizzle, marketed as lightweight, is slower than Sequelize (a full ORM from 2014) in every single category. The functional expression-tree approach creates more intermediate objects than Sequelize’s simple string concatenation.

2. Standalone query builders can’t beat a well-designed ORM.

Knex and Kysely have zero entity/relation overhead; they’re just SQL string builders. Yet UQL, a full ORM with entities, relations, and migrations, is faster than both in all 8 categories, by 1.5x on batch INSERT up to 4.9x on aggregates. The conventional wisdom (“ORMs are slow”) doesn’t hold when the ORM pre-computes its metadata and avoids intermediate allocations.

3. MikroORM pays double.

MikroORM v7 uses Kysely internally as its SQL generator (it replaced Knex in v7), so every query goes through two compilation layers: MikroORM → Kysely → SQL string. In these tables, MikroORM averages about 3.8x slower than Kysely alone (from 1.3x on UPSERT to 7.7x on complex $or). That’s the cost of layering abstractions.

How UQL gets there

I got curious why the gap was so large, so I dug into the approach. Most ORMs figure out your schema at query time: “What table does User map to? What column is companyId? Is it nullable?” They answer these questions on every single query.

UQL answers them once at startup. Field-to-column mappings, table names, and relation paths are all pre-computed into lookup tables before the first query runs. At query time, generating SQL is just reading from a cache.

The other difference is allocation. When TypeORM builds a SELECT, it creates a QueryBuilder, then an expression tree, then walks the tree to produce SQL. UQL pushes SQL fragments directly into a string buffer, creating no intermediate objects and no garbage-collection pressure.

When this matters in production

Database latency is 1-50ms and ORM overhead is microseconds, so for a low-traffic app the difference is noise. It starts to matter at scale. Take the WHERE + SORT + LIMIT query at 1,000 req/s: UQL (1,365K ops/s) spends under 1ms of CPU per second generating SQL, while MikroORM (73K ops/s) spends roughly 14ms, about 19x more CPU for the same queries before a single byte hits the network. In serverless, where you pay per ms of CPU, that shows up on the bill; in containers, it shows up as horizontal scaling cost.

Reproduce it

Full disclosure: I’m the author of UQL. That’s exactly why I built the benchmark as an independent repo anyone can audit and reproduce.

This SQL-generation benchmark itself is no longer maintained (see the note above); for the current, actively re-run benchmark and its repro steps, see the benchmark page. There’s also a broader feature-by-feature comparison on the comparison page.

In search of the perfect TypeScript ORM

Sat, 15 Jun 2024 00:00:00 GMT

Originally published on Medium.

UQL is a dependency-free TypeScript ORM for PostgreSQL, MySQL, MariaDB, SQLite and MongoDB.

What is an ORM?

An ORM provides a simpler way to interact with databases in an app: it lets developers work with data as objects.

What is a perfect ORM for TypeScript?

Below are the ideal features a TypeScript ORM should have, why such features are the most important ones, and how the existing ORMs fall short in most of these areas.

The top 5 features a perfect TypeScript ORM should have are:

1. Serializable queries

Queries that can travel between the layers of a system keep the design simple. If the client can send a query to the server over HTTP or websockets using the ORM’s own syntax, you no longer need an extra query language on top: the GraphQL => ORM => Database flow collapses to ORM => Database. Concretely:

No pseudo-language for queries and no context switching: the syntax is standard JSON, entirely declarative and serializable.
No additional servers and no extra steps in the build process.
Editors and IDEs understand the queries natively, without custom plugins or extensions.

2. Native TypeScript

Use TypeScript itself for everything: JSON queries, classes, and decorators.

Type-safe queries and models that are natively validated by the same language that you use to write your app.
Context-aware queries allow auto-completion of the appropriate operators and fields according to the different parts of a query.
Entity definition with standard classes and decorators to avoid the need for proprietary DSLs (as happens with Prisma), extra steps in the build process, and custom extensions for the editors.

3. Multi-level operators

Operations such as filter, sort, limit, project, and others work on any level of the queries (including relations and their fields).

4. Consistent API across databases

Write the queries for any database in a consistent way and then transparently optimize these queries for the configured database dialect.

5. Universal syntax (language agnostic)

Because the queries are standard JSON, they can be produced or consumed from any language: JSON is a first-class format in Python, Rust, Go, and virtually everything else. That also makes UQL implementations in other languages feasible.

Why do the current top 3 TypeScript ORMs fall short?

What does TypeORM lack to be a perfect ORM?

1. Lack of 100% serializable queries:

Notice how the LessThan operator is a function that has to be imported and called; that alone makes the query impossible to serialize.

import { LessThan } from 'typeorm';

const loadedPosts = await dataSource.getRepository(Post).findBy({
  likes: LessThan(10),
});

2. Lack of Native TypeScript:

The query dissolves into strings because relations and where accept any string, so any invalid string can go there.

const posts = await connection.manager.find(Post, {
  select: ['id'],
  relations: ['< anything can go here >'],
});

3. Lack of consistent API across databases:

In the section that TypeORM has for MongoDB, there is a self-explanatory warning about this.

4. Lack of Universal Syntax (language agnostic):

It relies on closures to support advanced queries (and not every language out there supports closures).

What does Prisma lack to be a perfect ORM?

1. Lack of Native TypeScript:

Context-switching between the custom DSL and TypeScript makes this process obtrusive.
Extra steps in the build process to generate the corresponding files from the custom DSL.
It is required to install a custom extension for VS Code to get (basic) autocompletion from the editor for the DSL, which is far from being as good and reliable as with TypeScript.

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model User {
  id        Int      @id @default(autoincrement())
  createdAt DateTime @default(now())
  email     String   @unique
  name      String?
  role      Role     @default(USER)
  posts     Post[]
}

2. Lack of consistent API across databases:

Prisma exposes low-level details about MongoDB that could be encapsulated by the ORM.

model User {
  id String @id @default(auto()) @map("_id") @db.ObjectId
  // Other fields
}

3. Lack of Universal Syntax (language agnostic):

It relies on its own proprietary DSL to define the models.

What does MikroORM lack to be a perfect ORM?

1. Lack of 100% serializable queries:

Notice how that query uses two separate methods, one for the update and another for the where; that structure cannot be serialized.

const qb = orm.em.createQueryBuilder(Author);

qb.update({ name: 'test 123', type: PublisherType.GLOBAL }).where({
  id: 123,
  type: PublisherType.LOCAL,
});

2. Lack of Native TypeScript:

Dissolves into strings: any string can go inside the fields array, so the query loses the possibility of being type-safe.

const author = await em.findOne(
  Author,
  {},
  {
    fields: ['name', 'books.title', 'books.author', 'books.price'],
  }
);

3. Lack of Multi-level operators:

What if you need to filter the records of a relation or sort them? This seems unachievable in a type-safe way from what can be seen in the MikroORM docs.

4. Lack of consistent API across databases:

import { EntityManager } from '@mikro-orm/mongodb';
const em = orm.em as EntityManager;
const qb = em.aggregate(/* ... */);

MikroORM exposes low-level details about MongoDB that could be encapsulated by the ORM.

Why is UQL the closest to a perfect ORM?

In short, because it was designed from the beginning with all of the above foundations. Let’s see how.

1. 100% serializable queries

Even the insert and update operations have a fully serializable API.

const lastUsers = await pool.findMany(User, {
  $select: { id: true, name: true, email: true },
  $sort: { createdAt: -1 },
  $limit: 20,
});

2. Native TypeScript with truly type-safe queries

Every operator and field is validated according to the context. For example, the possible values for the $select operator will automatically depend on the level.

const lastUsersWithProfiles = await pool.findMany(User, {
  $select: { id: true, name: true },
  $populate: {
    profile: { $select: { id: true, picture: true }, $required: true }
  },
  $sort: { createdAt: -1 },
  $limit: 20,
});

3. Multi-level operators

The operators work on any level. For example, $sort and $where can be applied to the relations and their fields in a type-safe and context-aware way.

const items = await pool.findMany(Item, {
  $select: { id: true, name: true },
  $populate: {
    measureUnit: {
      $select: { id: true, name: true },
      $where: { name: { $ne: 'unidad' } },
      $required: true,
    },
    tax: { $select: { id: true, name: true } },
  },
  $where: {
    price: { $gte: 1000 },
    name: { $istartsWith: 'A' },
  },
  $sort: {
    tax: { name: 1 },
    measureUnit: { name: 1 },
    createdAt: -1,
  },
  $limit: 100,
});

4. Consistent API across databases

One API for every database: the same entities and queries transparently work on any supported database, with the dialect-specific SQL (or MongoDB commands) generated under the hood. This makes it easier to switch from a Document to a Relational database (or vice-versa); the migration guide walks through what that move looks like coming from Mongoose.

5. Universal syntax across languages

Its syntax is standard JSON, so queries can be produced or consumed from other languages, enabling interoperation or even implementations of UQL in languages such as Python or Rust.

See more at uql-orm.dev. Please star it ⭐ on GitHub if you like the idea!

UQL | Blog

What does an ORM really cost you?

The results

Prisma

The nested read is where ORMs are actually decided

Run it yourself

Zero dependencies: what we deleted

One release, four dependencies gone

Then reflection went too

What one npm i puts on disk

What the small number doesn’t cover

Get started

Standard decorators: props & cons

What it looks like

The type you declare is checked against the property

What reflection was costing

What we gave up

The two things that nearly broke it

The codemod

Was it worth it

Get started

Semantic search: native vector similarity in a multi-dialect ORM

What it looks like

Entity setup

Key features

Distance projection

4 distance metrics

3 vector types

Vector indexes

Why $sort?

Get started

In search of the fastest TypeScript ORM

Methodology

The results

INSERT: 10 rows in batch

UPDATE: SET + WHERE

UPSERT: ON CONFLICT by id

DELETE: simple WHERE

SELECT: 1 field

SELECT: WHERE + SORT + LIMIT

SELECT: complex $or + operators

AGGREGATE: GROUP BY + COUNT + HAVING

Three things that surprised me

How UQL gets there

When this matters in production

Reproduce it

In search of the perfect TypeScript ORM

What is an ORM?

What is a perfect ORM for TypeScript?

1. Serializable queries

2. Native TypeScript

3. Multi-level operators

4. Consistent API across databases

5. Universal syntax (language agnostic)

Why do the current top 3 TypeScript ORMs fall short?

What does TypeORM lack to be a perfect ORM?

What does Prisma lack to be a perfect ORM?

What does MikroORM lack to be a perfect ORM?

Why is UQL the closest to a perfect ORM?

1. 100% serializable queries

2. Native TypeScript with truly type-safe queries

3. Multi-level operators

4. Consistent API across databases

5. Universal syntax across languages

What one `npm i` puts on disk

Why `$sort`?