JSON-native TypeScript ORM

UQL queries SQL databases and MongoDB with plain, type-safe JSON. No codegen, no query builder.

Using a coding agent? Copy the setup prompt

1
import { pool } from './uql.config.js';
2
import { User } from './entities.js';
3

4
await pool.findMany(User, {
5
  // the entity class types every key
6
  $select: { id: true, emial: true },
7
  // same three levels deep
8
  $populate: { posts: { $select: { titel: true } } },
9
  // and operators against the column type
10
  $where: { loginCount: { $like: 3 } },
11
});

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

3
@Entity()
4
export class Post {
5
  @Id({ type: Number }) id?: number;
6
  @Field({ type: String }) title?: string | null;
7
  @Field({ references: () => User }) authorId?: string | null;
8
  @ManyToOne({ entity: () => User, references: (post) => post.authorId }) author?: User;
9
}
10

11
@Entity()
12
export class User {
13
  @Id({ type: 'uuid' }) id?: string;
14
  @Field({ type: String }) email?: string | null;
15
  @Field({ type: Number }) loginCount?: number | null;
16
  @OneToMany({ entity: () => Post, mappedBy: (post) => post.author }) posts?: Post[];
17
}

1
import { PgQuerierPool } from 'uql-orm/postgres';
2
import { User } from './entities.js';
3

4
export const pool = new PgQuerierPool({
5
  connectionString: process.env.DATABASE_URL,
6
});
7

8
export default { pool, entities: [User] };

Every key is type-checked

A query is a plain object: no builder to chain, no operators to import. The compiler checks every key at any depth, and the operators ($in, $gte, $or, …) are MongoDB’s. The red lines in the editor above are real tsc errors against the published types: a misspelled field, the same typo inside a populated relation, and an operator the column’s type does not allow.

Entities are plain classes with standard decorators, so there is no schema file and no client to regenerate. Checking reaches into JSON dot-paths too. See Entities.

The same query, from browser to backend

A query is data, so the browser can send it over HTTP, typed the same as on the server:

1
import { HttpQuerier } from 'uql-orm/browser';
2

3
const http = new HttpQuerier('/api');
4

5
const { data } = await http.findMany(User, {
6
  $select: { id: true, email: true },
7
  $where: { email: { $endsWith: '@uql-orm.dev' } },
8
});

1
import { v7 as uuidv7 } from 'uuid';
2
import { Entity, Id, Field } from 'uql-orm';
3

4
@Entity()
5
export class User {
6
  @Id({ type: 'uuid', onInsert: uuidv7 })
7
  id!: string;
8

9
  @Field({ type: String, unique: true, nullable: false })
10
  email!: string;
11
}

1
import { PgQuerierPool } from 'uql-orm/postgres';
2

3
export const pool = new PgQuerierPool({
4
  connectionString: process.env.DATABASE_URL,
5
});

1
import { createFetchHandler } from 'uql-orm/http';
2

3
export const handler = createFetchHandler({ pool, include: [User] });

The handler runs each write in a transaction, takes authorization hooks, and mounts on Hono, Elysia, Next.js, Express, Bun or Workers. See the HTTP transport and the browser client.

The rest, briefly

Runs on PostgreSQL, PGlite, CockroachDB, MySQL, MariaDB, SQL Server, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun SQL and MongoDB, on Node 22.18+, Bun, Workers, Lambda and Vercel and the browser. ESM only.
Zero runtime dependencies; uql-orm/postgres is about 41 kB gzipped.
No N+1 queries: relations load in one statement.
Migrations with drift checks, vector search, raw SQL, multi-tenancy, soft delete, triggers and streaming in the same package.
The least overhead of any ORM we measured on a PostgreSQL round trip, on Bun and Node (benchmark).

Compare it feature by feature and on type safety.

UQL MIT License GitHub npm RSS llms.txt