Quick Start

UQL is the JSON-native query protocol for TypeScript. It is engineered to be fast, safe, and universally compatible.

Runs Everywhere: Node.js, Bun, Deno, Cloudflare Workers, Electron, React Native, and the Browser.
Unified API: A consistent interface for PostgreSQL, MySQL, MariaDB, SQLite, LibSQL, Neon, D1, and MongoDB.

1. Install

Install the core and your preferred driver:

npm install uql-orm pg # or mysql2, better-sqlite3, mongodb, etc.

bun add uql-orm
# Bun has native SQL drivers built-in via `bun:sql`, no external drivers required!

pnpm add uql-orm pg # or mysql2, better-sqlite3, mongodb, etc.

If you use the decorator-based approach, make sure your tsconfig.json has:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

If you use the imperative API (defineEntity), these flags are not required.

UQL is Modern Pure ESM — ensure your project’s module supports ESM imports (e.g., NodeNext, ESNext, Bundler).

2. Fast-Track Example

Here is a complete example of defining an entity, setting up a pool, and running a query.

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

@Entity()
export class User {
  @Id({ type: 'uuid' })
  id?: string;

  @Field({ unique: true })
  email?: string;

  @Field()
  name?: string;
}

// uql.config.ts
import type { Config } from 'uql-orm';
import { PgQuerierPool } from 'uql-orm/postgres';
import { User } from './entities.js';

const pool = new PgQuerierPool({ host: 'localhost', database: 'uql_app' });

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

// app.ts
import { pool } from './uql.config.js';
import { User } from './entities.js';

const users = await pool.transaction(async (querier) => {
  return await querier.findMany(User, {
    $select: { id: true, name: true },
    $where: { email: { $endsWith: '@uql-orm.dev' } },
    $limit: 10,
  });
});

console.log(users);

Supported Databases

Database	Driver Package	Status
Bun SQL Native	`bun:sql`	✅ Full
PostgreSQL	`pg`	✅ Full
CockroachDB	`pg`	✅ Full
MySQL	`mysql2`	✅ Full
MariaDB	`mariadb` or `mysql2`	✅ Full
SQLite	`better-sqlite3`	✅ Full
LibSQL / Turso	`@libsql/client`	✅ Full
Cloudflare D1	—	✅ Full
Neon	`@neondatabase/serverless`	✅ Full
MongoDB	`mongodb`	✅ Full

Import Paths

UQL uses subpath exports to keep your bundles lean:

Path	Purpose
`uql-orm`	Core decorators, types, and query utilities
`uql-orm/postgres`	PostgreSQL driver pool
`uql-orm/cockroach`	CockroachDB driver pool
`uql-orm/mysql`	MySQL driver pool (also works with MariaDB)
`uql-orm/maria`	MariaDB driver pool (dedicated `mariadb` driver)
`uql-orm/sqlite`	SQLite driver pool
`uql-orm/bunSql`	Bun Native SQL driver pool (Postgres, MySQL, SQLite)
`uql-orm/libsql`	LibSQL / Turso driver pool
`uql-orm/neon`	Neon serverless driver pool
`uql-orm/d1`	Cloudflare D1 driver pool
`uql-orm/mongo`	MongoDB driver pool
`uql-orm/express`	Express middleware (auto-generated REST APIs)
`uql-orm/browser`	Browser HTTP querier
`uql-orm/migrate`	Migration engine & CLI

Next Steps

Define Entities — Explore all decorators and type abstractions.
Define Relations — Map complex relationships with ease.
Querying — Deep selection, filtering, and sorting.
Transactions — Automatic and manual transaction patterns.
Migrations — Schema evolution with the CLI and Drift Detection.