# UQL

> A TypeScript ORM whose queries are plain JSON values: typed to the leaf, no codegen, and one API across Postgres, CockroachDB, MySQL, SQLite, MongoDB, and the edge.

Instructions for AI agents:

- Before writing UQL code, read the skill `uql-orm` ships: https://uql-orm.dev/.well-known/agent-skills/uql-orm/SKILL.md. In a project that installed `uql-orm`, the same file is at `node_modules/uql-orm/skills/uql-orm/SKILL.md` and matches that version.
- Every page below is Markdown at the URL listed. A page's HTML URL answers with the same Markdown when the request prefers `text/markdown`.
- The same docs are an MCP server at https://uql-orm.dev/mcp: `search_docs`, `get_doc` and `read_skill`.
- Setting up a coding agent for UQL: https://uql-orm.dev/ai-agents.md

## Overview

- [The JSON-native TypeScript ORM for Bun, Deno, Node](https://uql-orm.dev/index.md): UQL is a TypeScript ORM whose queries are plain JSON values, typed to the leaf, with no codegen and one API across every SQL database, MongoDB, and every runtime.
- [Quick Start](https://uql-orm.dev/getting-started.md): Install UQL, define an entity, and run your first query.
- [Switching to UQL](https://uql-orm.dev/switching-to-uql.md): Scaffold entities from the database you already run, translate the queries you already write, and move a production system over in phases.
- [Upgrade guide](https://uql-orm.dev/upgrade-guide.md): What each release asks of you, newest first, with the version and date it landed.
- [Codemod](https://uql-orm.dev/codemod.md): One command that rewrites your entities across the breaking changes that can be made mechanically.
- [AI & RAG](https://uql-orm.dev/ai-semantic-search.md): Build semantic search and RAG features in UQL with one type-safe query API.
- [AI Coding Agents](https://uql-orm.dev/ai-agents.md): Give your coding agent the UQL skill, the docs as Markdown, and a docs MCP server, so it writes UQL for the version you installed.
- [FAQ](https://uql-orm.dev/faq.md): Frequently asked questions about UQL ORM

## Comparison

- [ORM Comparison by Feature](https://uql-orm.dev/comparison.md): Side-by-side API comparison of Drizzle vs MikroORM vs Prisma vs TypeORM vs UQL, with actual code for every common operation.
- [ORM Benchmark](https://uql-orm.dev/benchmark.md): What each TypeScript ORM costs per request against a real PostgreSQL: Drizzle vs MikroORM vs Prisma vs Sequelize vs TypeORM vs UQL.
- [ORM Type Safety Comparison](https://uql-orm.dev/type-safety.md): Ordinary mistakes written in six TypeScript ORMs, compiled live: Drizzle vs MikroORM vs Prisma vs Sequelize vs TypeORM vs UQL.
- [What survives a rename? Six TypeScript ORMs](https://uql-orm.dev/rename-safety.md): Six ORMs renamed the way your editor renames, and compiled live: which mentions follow, which the compiler catches, and which break silently.

## Entities

- [Decorators](https://uql-orm.dev/entities/basic.md): Define entities with the @Entity, @Id, and @Field decorators, and choose column types.
- [Imperative Definition](https://uql-orm.dev/entities/imperative.md): Define entities without decorators using defineEntity, with the same options as the decorator API.
- [Runtime Schemas](https://uql-orm.dev/entities/runtime.md): Define entities from data (a CMS content type an admin creates, a tenant whose columns are rows in a table) and apply them to the database while the process runs.
- [Relations](https://uql-orm.dev/entities/relations.md): Define one-to-one, one-to-many, and many-to-many relations between UQL entities.
- [Computed Fields](https://uql-orm.dev/entities/computed-fields.md): Fields the database computes rather than the caller writes, spliced into each query or stored as a real column.
- [Soft Delete](https://uql-orm.dev/entities/soft-delete.md): Mark rows as deleted without removing them, using a softDelete field.
- [Optimistic Locking](https://uql-orm.dev/entities/optimistic-locking.md): Guard a write across requests with a version column, so an update against a row someone else changed throws instead of overwriting it.
- [Lifecycle Hooks](https://uql-orm.dev/entities/lifecycle-hooks.md): Run logic before and after insert, update, delete, and load operations with hook decorators and global listeners.
- [Indexes](https://uql-orm.dev/entities/indexes.md): Define simple and composite indexes on your entities with @Field({ index }) and @Index.
- [Enum + Checks](https://uql-orm.dev/entities/enum-checks.md): Enum fields and table-level CHECK constraints, so the database enforces what the entity declares.
- [Inheritance](https://uql-orm.dev/entities/inheritance.md): Share fields across entities with abstract base classes and inheritance in UQL.

## Queries

- [Example Entities](https://uql-orm.dev/querying/models.md): The shared entities every query example in this section imports, and the fields those examples select, filter and sort on.
- [Querier](https://uql-orm.dev/querying/querier.md): Learn how to use the querier to interact with any database through UQL.
- [Methods Reference](https://uql-orm.dev/querying/methods.md): Every querier and pool method, the IDs an insert reports back per database, and the upsert operations.
- [Deep Relations](https://uql-orm.dev/querying/relations.md): Populate, filter, and sort across related entities with $populate and relation operators.
- [Counting](https://uql-orm.dev/querying/counting.md): Count matching rows, test existence, page with a total, and count or rank by a relation's size, on every SQL dialect and MongoDB.
- [Sorting](https://uql-orm.dev/querying/sorting.md): Order rows with $sort, and say where nulls land so the answer is the same on every engine.
- [Comparison Operators](https://uql-orm.dev/querying/comparison-operators.md): Filter by equality, ranges, string matching, and lists with UQL comparison operators.
- [Logical Operators](https://uql-orm.dev/querying/logical-operators.md): Combine conditions with $and, $or, $not, and $nor in UQL queries.
- [Sub-Queries](https://uql-orm.dev/querying/sub-queries.md): Write correlated sub-queries and raw SQL fragments with the raw() helper in UQL.
- [Raw SQL](https://uql-orm.dev/querying/raw-sql.md): Execute vanilla SQL queries with type safety using all() and run().
- [Aggregate Queries](https://uql-orm.dev/querying/aggregate.md): Use GROUP BY, HAVING, COUNT, SUM, AVG, MIN, MAX, and DISTINCT with UQL's aggregate API.
- [JSON / JSONB](https://uql-orm.dev/querying/json.md): Work with JSON/JSONB fields with type-safe filtering, atomic updates, and sorting across PostgreSQL, MySQL, MariaDB, and SQLite.
- [Full-Text Search](https://uql-orm.dev/querying/full-text.md): Search and rank text with $text on PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite and MongoDB, with one index declaration and per-column weights.
- [Semantic Search](https://uql-orm.dev/querying/semantic-search.md): Vector similarity search with $vector, $near, $candidates, $distance, and $project across PostgreSQL, CockroachDB, MariaDB, SQLite, libSQL, Turso, MSSQL, and MongoDB Atlas.
- [Transactions](https://uql-orm.dev/querying/transactions.md): Run a unit of work all-or-nothing in UQL, pick an isolation level, and decide who owns the connection and the commit.
- [Error Handling](https://uql-orm.dev/querying/errors.md): Tell a duplicate, a missing parent or a deadlock apart with one function, on every engine UQL supports.
- [Row Locking](https://uql-orm.dev/querying/locking.md): Take a row-level lock with $lock, so a read-modify-write cannot lose an update, and build a work queue with SKIP LOCKED.
- [Cursor Streaming](https://uql-orm.dev/querying/streaming.md): Process millions of rows with a stable memory footprint using native driver-level cursors.
- [Query Filters](https://uql-orm.dev/querying/filters.md): Named, default-on $where fragments for soft-delete, multi-tenancy, and row-level security.

## Advanced

- [Pool](https://uql-orm.dev/pool.md): The object every query runs on: which one to build, how big, how long it lives, and how to close it.
- [Migrations](https://uql-orm.dev/migrations.md): Keep entities and your database schema in sync, in either direction, with the uql-migrate CLI.
- [Migration builder](https://uql-orm.dev/migrations/builder.md): Fluent, dialect-aware table and column definitions for hand-written UQL migrations.
- [Multi-tenancy](https://uql-orm.dev/multi-tenancy.md): Scope every query to the current tenant automatically with security filters and request context.
- [Multiple Schemas](https://uql-orm.dev/multiple-schemas.md): Put entities in different Postgres schemas, or give each tenant a schema of its own, with the same entity classes.
- [Serverless](https://uql-orm.dev/serverless.md): Run UQL in functions that freeze and thaw: pool placement, connection limits, and per-platform lifecycle.
- [Logging & Monitoring](https://uql-orm.dev/logging.md): Configure query logging, slow-query alerts, and custom loggers in UQL.
- [Naming Strategy](https://uql-orm.dev/naming-strategy.md): Configure global and per-entity naming strategies for tables and columns in UQL.

## Databases

- [Bun Native SQL](https://uql-orm.dev/bun-sql.md): Drive Bun's built-in SQL clients with UQL, one pool for Postgres, MySQL, MariaDB and CockroachDB.
- [Cloudflare D1](https://uql-orm.dev/cloudflare-d1.md): Run UQL on Cloudflare Workers with D1, including its limits and the transaction it does not have.
- [CockroachDB](https://uql-orm.dev/cockroachdb.md): Run UQL on CockroachDB over the Postgres wire protocol, and the differences that come with it.
- [MongoDB](https://uql-orm.dev/mongodb.md): Run UQL on MongoDB with the same entities and queries you use on SQL, and where the two differ.
- [Microsoft SQL Server](https://uql-orm.dev/mssql.md): Run UQL on SQL Server 2017 and up (MSSQL) with the mssql driver, and the behaviour that differs from the other engines.
- [MySQL & MariaDB](https://uql-orm.dev/mysql.md): Run UQL on MySQL with mysql2 or on MariaDB with its own driver, and the differences that matter.
- [PGlite](https://uql-orm.dev/pglite.md): Run UQL on PGlite, Postgres compiled to WASM and running in your own process.
- [PostgreSQL](https://uql-orm.dev/postgres.md): Run UQL on PostgreSQL with node-postgres: pooling, upserts, RLS, and cursor streaming.
- [SQLite](https://uql-orm.dev/sqlite.md): Run UQL on SQLite with Node's built-in driver, better-sqlite3, or bun:sqlite.
- [Supabase](https://uql-orm.dev/supabase.md): Run UQL on Supabase Postgres, pick the right pooler endpoint, and layer UQL security filters over Postgres RLS.
- [Turso & LibSQL](https://uql-orm.dev/turso.md): Run UQL on Turso Cloud from edge runtimes, on the embedded Turso engine, or on libSQL.

## Frameworks

- [HTTP (any framework)](https://uql-orm.dev/http.md): Serve UQL entities over HTTP from any framework with the framework-agnostic transport core.
- [Express](https://uql-orm.dev/express.md): Query UQL from your own Express routes, and optionally auto-generate REST endpoints with the querier middleware.
- [Fastify](https://uql-orm.dev/fastify.md): Query UQL from your own Fastify routes, and optionally serve entity CRUD by bridging the framework-agnostic request handler.
- [Hono](https://uql-orm.dev/hono.md): Query UQL from your own Hono routes, and optionally mount entity CRUD with the fetch-native transport core.
- [Elysia](https://uql-orm.dev/elysia.md): Query UQL from your own Elysia routes, and optionally mount entity CRUD with the fetch-native transport core.
- [NestJS](https://uql-orm.dev/nestjs.md): Use UQL in NestJS with the UqlModule, injectable querier pool, and auto-generated entity routes.
- [Next.js](https://uql-orm.dev/nextjs.md): Use UQL in Next.js App Router server components, route handlers, and server actions.
- [React Router](https://uql-orm.dev/react-router.md): Use UQL in React Router framework mode loaders, actions, resource routes, and middleware.
- [Astro](https://uql-orm.dev/astro.md): Query UQL from Astro pages, server islands, actions, and a catch-all API endpoint.
- [TanStack Start](https://uql-orm.dev/tanstack-start.md): Use UQL in TanStack Start via type-safe server functions and a catch-all server route that mounts the HTTP transport core.
- [tRPC](https://uql-orm.dev/trpc.md): Expose UQL entities as tRPC procedures with the serializable JSON query as procedure input.
- [oRPC](https://uql-orm.dev/orpc.md): Expose UQL entities as oRPC procedures with type-safe pass-through inputs.
- [Browser](https://uql-orm.dev/browser.md): Run type-safe UQL queries from the browser, either against your API with HttpQuerier or against Postgres itself with PGlite.
- [TanStack Query](https://uql-orm.dev/react-query.md): Use UQL's serializable queries as TanStack Query cache keys, with query options factories, pagination, mutations, optimistic updates and SSR hydration.

## Optional

- [Every page](https://uql-orm.dev/llms-full.txt): the whole site in one file, comparisons and blog posts included
- [In search of the fastest TypeScript ORM](https://uql-orm.dev/blog/in-search-of-the-fastest-typescript-orm.md): A SQL-generation speed benchmark across 6 TypeScript ORMs and query builders (Drizzle, Knex, MikroORM, Sequelize, TypeORM, and UQL), with a reproducible open-source methodology.
- [In search of the perfect TypeScript ORM](https://uql-orm.dev/blog/in-search-of-the-perfect-orm.md): What makes a perfect TypeScript ORM? A breakdown of five features: serializable queries, native TypeScript, multi-level operators, one API across databases, and language-agnostic JSON syntax, and where today's ORMs fall short.
- [In search of the type-safest ORM](https://uql-orm.dev/blog/in-search-of-the-type-safest-orm.md): Reading a column your query never selected is undefined at runtime and silent at compile time. I resisted fixing it for a while, because narrowing a row takes something away. Then I checked what my own projects actually do.
- [How much memory does an ORM cost per request?](https://uql-orm.dev/blog/measuring-orm-memory.md): Weighing the heap around a query looked like an afternoon's work. I got three plausible wrong answers first: zero bytes on Bun, a 19% skew from forcing a collection, and a ranking that turned out to be the running order.
- [Semantic search: native vector similarity in a multi-dialect ORM](https://uql-orm.dev/blog/semantic-search.md): UQL 0.3 brings native vector similarity search to PostgreSQL, MariaDB, SQLite, and MongoDB Atlas through one type-safe query API, including automatic index migration for AI and RAG workloads.
- [Standard decorators: props & cons](https://uql-orm.dev/blog/standard-decorators.md): uql-orm 0.23 moved from legacy TypeScript decorators to the TC39 standard spec. No compiler flags, no reflect-metadata, and a type check that legacy decorators structurally could not do. The cost: three decorators deleted, NestJS locked out, and type on every field.
- [What does an ORM really cost you?](https://uql-orm.dev/blog/what-orms-really-cost.md): A full PostgreSQL round trip through six ORMs: insert, read, update, read, nested read, delete, read. What each one adds over hand-written driver code, where Prisma loses two thirds of a millisecond on one step, and why totals hide all of it.
- [Zero dependencies: what we deleted](https://uql-orm.dev/blog/zero-dependencies.md): uql-orm installs one package, 288 kB on the wire, no runtime dependencies, every dialect included. Here is what came out to get there: reflect-metadata, jiti, tslib, sqlstring, 369 sourcemaps, and the changelog.