UQL | Blog

The SQL tag: a function called without parentheses

Fri, 09 Oct 2026 00:00:00 GMT

Here is a line from UQL v0.100.x:

await pool.all`SELECT * FROM "User" WHERE "email" = ${email}`;

No parentheses, yet this is still a function call. How JavaScript makes that call is what keeps (vanilla) email out of the SQL; yes, it will be automatically sanitized. “But how?” you may ask, and here is the answer below.

What a tag receives

A template literal with a function name is a tagged template. It is plain JavaScript, there since ES2015, so it runs in every browser, Node and Bun with no build step.

The JS engine calls the tag with the template cut into pieces: first an array of the literal text, then each ${} value as an argument of its own. A tag that prints its arguments shows the split.

For example:

function show(texts: TemplateStringsArray, ...values: unknown[]) {
  console.log(texts, values);
}

show`SELECT * FROM "User" WHERE "email" = ${'ana@example.com'} AND "age" > ${18}`;
// ['SELECT * FROM "User" WHERE "email" = ', ' AND "age" > ', '']  ['ana@example.com', 18]

There is always one more string than there are values; here the last one is empty.

From pieces to a query

The text pieces come from your (static) source code. The values are dynamic, and can come from anywhere (users, other apps, microservices, etc.) at run time. A database driver mandates exactly that split: SQL with placeholders, and the parameters beside it.

So this:

function sql(texts: TemplateStringsArray, ...values: unknown[]) {
  const text = texts.reduce((t, part, i) => `${t}$${i}${part}`);
  return { text, values };
}

sql`SELECT * FROM "User" WHERE "email" = ${email}`;

Produces this:

{ text: 'SELECT * FROM "User" WHERE "email" = $1', values: ['ana@example.com'] }

Whatever email holds, even a SQL injection attempt as '; DROP TABLE "User"; --, is sent as the value of $1, never as SQL. No manual escaping needed, no SQL injection.

In UQL the method is the tag: all and run take the template directly, so there is no sql helper to import and wrap.

The parentheses trap

Add parentheses and you have a different program:

await pool.all`SELECT * FROM "User" WHERE "email" = ${email}`;

// @ts-expect-error a plain string, with the value already inside it
await pool.all(`SELECT * FROM "User" WHERE "email" = ${email}`);

The second line builds the whole string first, email and all, and hands the function the finished text. No library can take the value back out. That is why, in UQL, that last line does not compile.

What TypeScript adds

TypeScript checks each ${} against the tag’s parameter types, so UQL can say what a database can bind: strings, numbers, booleans, bigint, Date, bytes, null, lists of those, and SQL fragments. Two common slips stop at the compiler.

For example:

// @ts-expect-error `status` may be undefined, which binds nothing
await pool.all`SELECT * FROM "User" WHERE "status" = ${status}`;

// @ts-expect-error an object is not a SQL value
await pool.run`UPDATE "User" SET "prefs" = ${prefs} WHERE "id" = ${id}`;

// this one compiles
await pool.run`UPDATE "User" SET "prefs" = ${JSON.stringify(prefs)} WHERE "id" = ${id}`;

A tag also takes a type argument, so pool.all<{ id: number; email: string }>`...` hands back typed rows.

Fragments

raw is the same tag without running anything: it returns a fragment. A fragment inside another template is spliced in, its values still bound:

import { raw } from 'uql-orm';

const conditions = [raw`"createdAt" > ${since}`];
if (status) conditions.push(raw`"status" = ${status}`);

await pool.all`SELECT * FROM "User" WHERE ${raw.join(conditions, ' AND ')}`;

For trusted SQL held in a string, such as a file’s contents, use raw.text(sql). It is the only call that binds nothing, so it is easy to find in a review. A tag binds values, not names: a table or column taken from user input still needs checking against a list you control.

Also in 0.100.0

`undefined` in a filter throws

Prisma’s docs warn that deleteMany({ where: { id: undefined } }) deletes every user, because an undefined key is dropped from the filter; UQL used to drop it too, but now it throws:

await pool.deleteMany(User, { $where: { email: maybeEmail } });
// UqlUsageError: $where on 'User' holds undefined at 'email': leave the key out not to filter by it, or name null

Writes that do what the code says

A transaction() inside another is a savepoint, so a failing inner step rolls back alone. A to-many update keeps the children the payload lists and removes the rest. Any write can take returning and resolve to the rows it wrote, typed by the fields you name.

By the way, how to quickly move to all this?

npx uql-codemod updates your imports and turns all(sql, [a, b]) into a tag. Anything it cannot convert safely is listed for you. The upgrade guide has the rest.

UQL is a JSON-native TypeScript ORM for Node.js and Bun. Supports PostgreSQL, PGlite, MySQL, MariaDB, MSSQL, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.

Type-safe triggers in an ORM. What?

Sat, 26 Sep 2026 00:00:00 GMT

An audit log written by a lifecycle hook passes every test. Then someone runs a backfill, fixes a row in psql, or points a second service at the table, and the log has a gap. Nothing failed: an ORM hook only sees the ORM’s own writes.

A database trigger sees every write. In UQL you declare it on the entity, the compiler checks its body, and uql renders it for each SQL engine.

The audit log, on the entity

Triggers usually live as SQL strings in an old migration: invisible from the model, unchecked against the columns, and written again for every engine. Here the trigger sits beside the table it watches:

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

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

  @Field({ type: Number, name: 'post_id', nullable: false })
  postId?: Post['id'];

  @Field({ type: String, name: 'from_status' })
  fromStatus?: Post['status'];

  @Field({ type: String, name: 'to_status' })
  toStatus?: Post['status'];
}

@Trigger({
  on: 'afterUpdate',
  name: 'audit',
  of: (post) => [post.status],
  run: (newRow, oldRow) =>
    insertInto(PostAudit, {
      postId: newRow.id,
      fromStatus: oldRow.status,
      toStatus: newRow.status,
    }),
})
@Entity()
export class Post {
  @Id({ type: Number })
  id?: number;

  @Field({ type: String })
  status?: string | null;
}

of fires the trigger only when status changes, and run writes the audit row. Columns are read as properties, so the compiler knows every name and type. A where adds conditions on either row, such as { $old: { status: 'draft' } }.

What the compiler catches

Each of these fails at build time, not when the trigger first fires:

import { defineTrigger, insertInto } from 'uql-orm';

defineTrigger(Post, {
  on: 'afterInsert',
  run: (_newRow, oldRow) => insertInto(PostAudit, { postId: oldRow.id }), // error: no old row on insert
});

defineTrigger(Post, {
  on: 'afterUpdate',
  run: (newRow) => insertInto(PostAudit, { post: newRow.id }), // error: PostAudit has no `post`
});

defineTrigger(Post, {
  on: 'afterUpdate',
  run: (newRow) => insertInto(PostAudit, { postId: newRow.status }), // error: postId holds a number
});

So does watching a column the entity lacks, or an updateTable or deleteFrom with no $where, which would hit every row on every fire.

One declaration, every SQL engine

This is what sync and generated migrations install. CockroachDB gets the Postgres form, MariaDB the MySQL one:

CREATE OR REPLACE FUNCTION "_uql_Post__audit_0a57e9"() RETURNS trigger AS $uql$
BEGIN
  INSERT INTO "PostAudit" ("post_id", "from_status", "to_status")
    VALUES (NEW."id", OLD."status", NEW."status");
  RETURN NULL;
END $uql$ LANGUAGE plpgsql;

CREATE TRIGGER "_uql_Post__audit_0a57e9"
AFTER UPDATE OF "status" ON "Post"
FOR EACH ROW
WHEN (OLD."status" IS DISTINCT FROM NEW."status")
EXECUTE FUNCTION "_uql_Post__audit_0a57e9"()

CREATE TRIGGER `_uql_Post__audit_94c077`
AFTER UPDATE ON `Post`
FOR EACH ROW
BEGIN
  IF NOT (OLD.`status` <=> NEW.`status`) THEN
    INSERT INTO `PostAudit` (`post_id`, `from_status`, `to_status`)
      VALUES (NEW.`id`, OLD.`status`, NEW.`status`);
  END IF;
END

CREATE TRIGGER `_uql_Post__audit_08d35c`
AFTER UPDATE OF `status` ON `Post`
FOR EACH ROW
WHEN (OLD.`status` IS NOT NEW.`status`)
BEGIN
  INSERT INTO `PostAudit` (`post_id`, `from_status`, `to_status`)
    VALUES (NEW.`id`, OLD.`status`, NEW.`status`);
END

CREATE TRIGGER "_uql_Post__audit_d8fbff"
ON "Post" AFTER UPDATE
AS
BEGIN
  SET NOCOUNT ON;
  INSERT INTO "PostAudit" ("post_id", "from_status", "to_status")
    SELECT inserted."id", deleted."status", inserted."status"
    FROM inserted JOIN deleted ON inserted."id" = deleted."id"
    WHERE EXISTS (SELECT deleted."status" EXCEPT SELECT inserted."status");
END

“Fire only when status changes” has to count NULL to 'draft' as a change, which a plain <> does not. Each engine spells that differently, and SQL Server hands the trigger tables rather than rows: four chances to get it subtly wrong by hand.

How other ORMs do it

The same trigger, on PostgreSQL only:

Drizzle, Prisma, TypeORM
MikroORM

-- No trigger API. This goes in a hand-written migration: `drizzle-kit generate --custom`,
-- `prisma migrate dev --create-only`, or `queryRunner.query(...)` in a TypeORM migration.
CREATE FUNCTION post_audit() RETURNS trigger AS $$
BEGIN
  INSERT INTO post_audit (post_id, from_status, to_status)
    VALUES (NEW.id, OLD.status, NEW.status);
  RETURN NULL;
END $$ LANGUAGE plpgsql;

CREATE TRIGGER post_audit AFTER UPDATE OF status ON post
FOR EACH ROW WHEN (OLD.status IS DISTINCT FROM NEW.status)
EXECUTE FUNCTION post_audit();

MikroORM

// Declared on the entity and installed by migrations. The callback maps property names to
// column names; the body and `when` around them are SQL strings, one set per dialect.
import { defineEntity, p } from '@mikro-orm/core';

const PostSchema = defineEntity({
  name: 'Post',
  properties: {
    id: p.integer().primary(),
    status: p.string().nullable(),
  },
  triggers: [
    {
      name: 'post_audit',
      timing: 'after',
      events: ['update'],
      when: 'OLD.status IS DISTINCT FROM NEW.status',
      body: (c) =>
        `INSERT INTO post_audit (post_id, from_status, to_status)
         VALUES (NEW.${c.id}, OLD.${c.status}, NEW.${c.status}); RETURN NULL;`,
    },
  ],
});

MikroORM comes closest: the trigger lives on the entity and takes column names from its metadata, but the SQL around them is a string, unchecked and written once per engine. TypeORM’s subscribers, like hooks, only see TypeORM’s own writes.

Keeping them in sync

sync and generate:entities install what an entity declares and drop what it no longer does. Each name ends in a hash of its SQL, so an unchanged trigger is left alone and an edited one is replaced. Triggers uql did not create are never touched.

Where it stops

MongoDB has no triggers, so a write to an entity declaring one is refused rather than made without it.
raw bodies are not translated: write one that runs on every engine you use, or one per engine.
Entity filters do not apply inside a trigger: soft delete and security do not scope its writes, so scope them by the row’s own columns.

The engine-specific rules are on the Triggers page.

Why it matters with coding agents

Agents write much of the code that touches a database, including what hooks never see: a one-off script, a backfill, a quick UPDATE. A rule the database enforces holds for all of it, and a trigger on the entity sits in the file the agent reads, checked by the compiler it runs.

Hook, trigger or stamp

You need	Use
Logic around UQL’s own writes: call an API, publish an event, validate	a lifecycle hook
A row the database writes whoever changes the table, like an audit	a trigger
A column the database keeps current on every write, like `updatedAt`	a stamp

A stamp is a trigger uql writes the body of. currentTimestamp is the database clock, in UTC to the millisecond on every engine:

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

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

  @Field({ type: Date, computed: currentTimestamp, stored: ['update'] })
  readonly updatedAt?: Date | null;
}

Get started

Triggers: every option, the SQL per engine, and the engine notes
Comparison: triggers and the rest of the feature matrix, ORM by ORM
GitHub

If a trigger you need cannot be declared this way, open an issue with the SQL you would have written.

What a rename breaks: six TypeScript ORMs

Mon, 21 Sep 2026 00:00:00 GMT

You pick a TypeScript ORM also for the type safety, right? Then press F2, the editor renames what it can see (automatically), and the rest of the schema quietly keeps the old name (unsynced).

One model, 19 places that name three of its members: indexes, both sides of a relation, a check constraint, a projection, raw SQL in a filter.

I pressed F2 on emailAddress to email, employerId to workplaceId, employer to workplace in each and counted what got left behind.

renamed
stopped by the compiler
left behind silently

import { count, eq, relations, type SQL, sql } from 'drizzle-orm';
import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
import {
  check,
  index,
  integer,
  pgTable,
  serial,
  text,
  uniqueIndex,
} from 'drizzle-orm/pg-core';

export const companies = pgTable('Company', { id: serial().primaryKey() });

export const users = pgTable(
  'User',
  {
    id: serial().primaryKey(),
    emailAddress: text().notNull(),
    employerId: integer().references(() => companies.id),
    // Generated column
    emailLower: text().generatedAlwaysAs(
      (): SQL => sql`lower(${users.emailAddress})`,
    ),
  },
  (t) => [
    // Index on the field
    index().on(t.emailAddress),
    // Composite unique index
    uniqueIndex().on(t.emailAddress, t.employerId),
    // Covering index column | n/a: Drizzle's index builder has no INCLUDE
    // Expression index
    index().on(sql`lower(${t.emailAddress})`),
    // Partial index condition
    index()
      .on(t.employerId)
      .where(sql`${t.emailAddress} <> ''`),
    // Check constraint
    check('address_present', sql`${t.emailAddress} <> ''`),
  ],
);

export const usersRelations = relations(users, ({ one }) => ({
  // Foreign key of a relation
  employer: one(companies, {
    fields: [users.employerId],
    references: [companies.id],
  }),
}));

export const companiesRelations = relations(companies, ({ many }) => ({
  // Inverse side of a relation
  staff: many(users),
}));

const schema = { companies, users, usersRelations, companiesRelations };
declare const db: NodePgDatabase<typeof schema>;

// Field in the projection
await db.select({ id: users.id, address: users.emailAddress }).from(users);

// Field in the filter
await db.select().from(users).where(eq(users.emailAddress, 'ada@example.com'));

// Field in the sort
await db.select().from(users).orderBy(users.emailAddress);

// Field inside a loaded relation
await db.query.companies.findMany({
  with: { staff: { columns: { emailAddress: true } } },
});

// Relation loaded by name
await db.query.users.findMany({ with: { employer: true } });

// Field in inserted data
await db.insert(users).values({ emailAddress: 'ada@example.com' });

// Field in updated data
await db
  .update(users)
  .set({ emailAddress: 'ada@example.com' })
  .where(eq(users.id, 1));

// Foreign key in a grouped count
await db
  .select({ company: users.employerId, total: count() })
  .from(users)
  .groupBy(users.employerId);

// Field read off the result
const [user] = await db.select().from(users);
export const address = user.emailAddress;

// Raw SQL in a filter
await db
  .select()
  .from(users)
  .where(sql`lower(${users.emailAddress}) = ${'ada@example.com'}`);

rename-safety/drizzle.ts · static preview

Two ways to miss

A name the rename missed fails in one of two ways (and they’re not the same problem).

Some stop compiling. That costs an afternoon: tsc hands you the list, you work through it, nothing reaches production.

The rest compile. The build is green, the tests that don’t touch that query pass, and the failure turns up later as a column that isn’t there.

ORM	Followed the rename	Stopped by the compiler	Left behind silently
UQL	19	0	0
Drizzle	14	4	0
TypeORM	12	0	5
Prisma	4	7	3
Sequelize	4	0	12
MikroORM	3	13	3

Rows don’t all add up to 19: where an ORM can’t express a probe, there’s nothing to rename and nothing to count.

Don’t read the first column on its own

MikroORM follows the fewest renames of the six, yet it is among the safest.

Its defineEntity builder types index properties against the entity, so the stale name in { properties: ['emailAddress'] } is a compile error. 13 of its misses stop the build, 3 get through. Go by the leftmost column and you’d worry about the wrong tool. I did, for about a day.

Sequelize is the one to worry about. Its classes are properly typed and InferAttributes does real work on the model, but everything around the model takes strings, and nothing checks them:

Sequelize

// an index on a column that will not exist
User.init(attributes, { sequelize, indexes: [{ fields: ['emailAddress'] }] });

// an association pointing at a key that will not exist
User.belongsTo(Company, { foreignKey: 'employerId', as: 'employer' });

// queries asking for an attribute and a relation that will not exist
await User.findAll({ attributes: ['id', 'emailAddress'] });
await User.findAll({ include: ['employer'] });

All four compile after the rename. So do 12 of the 19 probes, and nothing warns you about any of them.

TypeORM: decorators fine, strings not

In TypeORM, the decorators aren’t the problem. @Index((user: User) => [user.employerId]) takes a callback, so F2 edits it and a stale name is a type error. That part works.

The SQL inside those same decorators doesn’t:

TypeORM

@Index((user: User) => [user.employerId], { where: `"emailAddress" <> ''` })
@Check(`"emailAddress" <> ''`)
@Column({ generatedType: 'STORED', asExpression: 'lower("emailAddress")' })

The callback half renames and the string half doesn’t. Three of TypeORM’s 5 silent misses are that pattern; the other two are an inverse relation and a query.

The whole table comes down to one question: whether the name goes through something the compiler resolves. mappedBy((user) => user.employer) is a property read. as: 'employer' is a string that looks like one. Drizzle sits high because its schema is values its queries import, so a stale name either follows or fails to compile. UQL follows all 19 because it never took a string option anywhere, indexes, checks and raw SQL included.

The files, the renames and every verdict are ts-orm-benchmark’s, on each ORM’s current stable release and its most type-safe entity API. Every rename is TypeScript 7.0.2’s own, or prisma-language-server 31.12.15’s for schema.prisma. I wrote UQL, so weigh that last row accordingly and then go check it: the rename page runs the real compiler in your browser instead of showing you my screenshot of it. Press F2 yourself.

In search of the type-safest ORM

Sun, 30 Aug 2026 00:00:00 GMT

The type-safety benchmark writes ten ordinary mistakes in six ORMs’ own APIs and compiles them, so “type-safe” stops being a word on a homepage and becomes a count. UQL caught nine. This is the story of the tenth, and of why I refused to fix it for a while.

The mistake

const [user] = await pool.findMany(User, {
  $select: { id: true, name: true },
});

user.email; // undefined at runtime. Every time.

The email column was never selected, so the property is not there. Nothing objected, because the result was typed as the whole entity no matter what the query asked for. The undefined travels into a response body or the next update, and surfaces days later as a null column nobody wrote.

Why I left it alone (temporarily)

I knew how to fix it. At first I didn’t want to, and the reason wasn’t the type machinery.

Narrowing takes something away. Once a row is { id, name } instead of User, it stops being the loose bag application code likes to pass around: hand it to a helper typed (user: User) => ... and it’s rejected. I wasn’t keen to trade a daily convenience for a compile error on a mistake I rarely make.

So I built it, upgraded every project I maintain, the professional ones included, and counted the damage. There was none: Variability alone has 200+ find calls across 25+ files, and it compiled clean, unchanged.

The pattern I was protecting turned out to be one I don’t actually write. Code that tops up a row starts from a full entity, because it needs the fields; code that projects ships the row straight out, to an API response, a list, a picker.

Why UQL still catches the typo

To shape the row, the query has to be captured as a type parameter, and that is where TypeScript changed. TypeScript 6.0 stopped reporting unknown keys on a literal checked against a captured map. Prisma’s and Drizzle’s projections are exactly that shape, which is why a misspelled column compiles for both today, and why they sit at nine and eight rather than ten.

UQL captures the field names instead of the map that holds them, so the compiler is asked a different question:

$select: { id: true, emial: true }

// against a captured map:  is 'emial' a known key?   - no longer reported
// against captured names:  'id' | 'emial' extends FieldKey<User>?   - 'emial' is not a field

The second is a constraint, and constraints never went anywhere. $where, $sort and each populated relation aren’t captured at all, so they keep the checks they always had.

What does it look like now?

The row is what you asked for, and the compiler knows it:

const [user] = await pool.findMany(User, {
  $select: { name: true },
  $populate: { posts: { $select: { id: true, title: true } } },
});

user.name; // string
user.posts.map((post) => post.title); // a list, empty at worst, no guard needed
user.email; // compile error: not selected
user.profile; // compile error: not populated

A query with no projection still returns the whole entity, so nothing changes where you didn’t ask for anything. And where a helper genuinely has to take a projected row, name the shape rather than widening the query:

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

type UserCard = QueryFindResult<User, 'id' | 'name'>;

That is ten of ten on the benchmark, the only entry with no red mark.

Each ORM's ten mistakes, underlined by the compiler as the tab changes. Type it yourself.

Ten probes can’t separate six ORMs the way a microsecond can, and I chose the ten. So the claim is the narrow one: these are ten mistakes people make on an ordinary afternoon, and this is the ORM that refuses all of them. Every probe is in type-safety/, compiled as written and again with each mistake corrected. Clone it and check.

And if you’re where I was, weighing a check you suspect you won’t need against a convenience you’re sure you use: upgrade a branch and count the damage. It’s a cheaper argument than the one I had with myself.

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

Thu, 27 Aug 2026 00:00:00 GMT

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 queryVec = await embed('How do vector indexes work?');

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

UQL generates the right SQL for your database:

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

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

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((article) => [article.embedding], {
  type: 'hnsw',
  distance: 'cosine',
  m: 16,
  efConstruction: 64,
})
export class Article {
  @Id({ type: Number }) id?: number;
  @Field({ type: String }) title?: string | null;

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

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

What else shipped

$project returns the computed distance as a named field, typed with the exported WithDistance helper, without computing it twice. Alongside it came four distance metrics (cosine, l2, inner, l1), three vector types (vector, halfvec, sparsevec), and HNSW, IVFFlat and native vector indexes, each where the engine has it. Which engine has which lives in the reference, kept current as engines are added.

Why `$sort`?

Vector similarity search is fundamentally sorting by distance. UQL reuses the existing $sort API, which combines 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.

Standard decorators: props & cons

Sun, 16 Aug 2026 00:00:00 GMT

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. This post covers both sides.

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 | null;

  @Field({ references: () => Company })
  companyId?: number | null;

  @ManyToOne({ entity: () => Company, references: (user) => user.companyId })
  company?: Company;
}

It is more typing: type on every field and entity on every relation, because nothing is reflected any more. The next section shows what the compiler does with it.

The declared type is checked against the property

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:

packages/uql-orm/src/entity/metadata/definition.ts (0.22)

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

Reflection only filled in a missing type; it never checked a stated one against the property.

The standard spec hands a field decorator a ClassFieldDecoratorContext<This, Value>, which is generic in the field’s value type. That difference means a decorator can now 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, references: (user) => user.companyId })
company?: number;         // error: a Company relation holds a Company, not its key

@OneToMany({ entity: () => User, mappedBy: (user) => user.company })
users?: User;             // 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?: string;        // error: User's key is a number, so this column is one too

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

None of these were catchable before. The migration did not introduce these bugs; it made existing ones 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 also did less than it seemed. 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

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

@Transactional() and currentQuerier() are gone too, since 0.29.0. Nothing but the decorator ever published that ambient querier, so currentQuerier() threw inside pool.transaction() and every other entry point. A transaction is pool.transaction(async (querier) => ...), which needs no class, no decorator and no async-local storage.

@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 took time to track down.

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 --dry-run
npx uql-codemod

It rewrites @Field/@Id types, relation entity getters and Relation<T> to T, 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, every removed decorator, options objects it cannot read, and branded string ids.

tsc does the rest of the migration. 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, though 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.

It did cost something: 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 --dry-run

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

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

How much memory does an ORM cost per request?

Thu, 13 Aug 2026 00:00:00 GMT

Someone on r/bun asked how UQL’s RAM usage compares to Drizzle’s. I didn’t have an answer, so I measured it: weigh the heap, run the query, weigh it again, subtract.

Three wrong numbers at the beginning

Bun reported zero. JavaScriptCore refreshes heapUsed only when it collects, so every entry looked like it had allocated nothing. The memory run is on Node, minus the two Bun SQL entries.

A forced global.gc() added 19%. It frees compiled code along with the garbage, and the rounds after it re-optimise as they run, allocating extra.

One process ranked them by start order. The first entry paid to JIT what the rest inherited warm. One process per entry now.

What came out

Against hand-written raw pg, rows mapped by hand, so what you see is the ORM’s own allocation.

Entry	Total KB	Adds KB
raw pg	245	floor
UQL	446	+201
Drizzle	769	+524
Prisma	1,053	+808
TypeORM	1,065	+820
Sequelize	1,296	+1,051
MikroORM	3,864	+3,619

18x between lightest and heaviest, where the same lifecycle in time spans 10x. One step causes nearly all of it: the nested read, the only one that turns two result sets into an object graph, costs UQL 184KB and MikroORM 2,060KB.

What survives

Sixty more lifecycles, collected either side, leave the worst entry 42KB heavier (Sequelize), identity maps and all. What the table prices is the garbage each request hands the collector, not memory that stays.

The answer

UQL adds 201KB per request, Drizzle 524KB, MikroORM 3.6MB. That is allocation, not resident memory, on one machine with no pooling and no concurrency.

Run it yourself: bun run bench.memory rewrites the table it publishes, so the current numbers can never drift from the last run.

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

Figures as measured when this was written, on pg throughout. The harness is re-run as versions move, so the current results will differ.

Adds is the number to read. 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 reasonable, but it does not explain the gap: 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 step matters most, because turning two result sets into an object graph without an N+1 is the main job of an ORM, and here the field spans 3.5x.

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 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

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]'. It did not crash or warn; the output was just wrong. 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 are compressed, but a cold start loads the unpacked files.

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 caveat about this table: 93% of @prisma/client is 70 MB of Rust query compilers cross-compiled to WebAssembly, one per engine it supports. 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 small; your driver may not be. 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, so the budget was added after that.

Get started

npm i uql-orm

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

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. 6 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, 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
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
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
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
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
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
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
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
Drizzle	74K	0.05x
MikroORM	69K	0.05x

Interactive charts

Two 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. A standalone query builder can’t beat a well-designed ORM.

Knex has zero entity/relation overhead; it’s just a SQL string builder. Yet UQL, a full ORM with entities, relations, and migrations, is faster 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.

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.

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.

TypeORM

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.

TypeORM

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.

MikroORM

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.

MikroORM

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:

MikroORM

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 for you. 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

The SQL tag: a function called without parentheses

What a tag receives

From pieces to a query

The parentheses trap

What TypeScript adds

Fragments

Also in 0.100.0

undefined in a filter throws

Writes that do what the code says

By the way, how to quickly move to all this?

Type-safe triggers in an ORM. What?

The audit log, on the entity

What the compiler catches

One declaration, every SQL engine

How other ORMs do it

Keeping them in sync

Where it stops

Why it matters with coding agents

Hook, trigger or stamp

Get started

What a rename breaks: six TypeScript ORMs

Two ways to miss

Don’t read the first column on its own

TypeORM: decorators fine, strings not

In search of the type-safest ORM

The mistake

Why I left it alone (temporarily)

Why UQL still catches the typo

What does it look like now?

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

What it looks like

Entity setup

What else shipped

Why $sort?

Get started

Standard decorators: props & cons

What it looks like

The declared type 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

How much memory does an ORM cost per request?

Three wrong numbers at the beginning

What came out

What survives

The answer

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

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

Two 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

`undefined` in a filter throws

Why `$sort`?

What one `npm i` puts on disk