Quick Start

UQL is a type-safe TypeScript ORM whose queries are plain JSON, so the same query works on the server, in the browser, micro-services, and over the network.

---

1. Install

Install the core and your preferred driver:

npm

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

bun

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

pnpm

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

TypeScript Setup

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) instead, these flags are not required.

UQL is ESM-only, so ensure your project’s module supports ESM imports (e.g., NodeNext, ESNext, Bundler).

---

2. Complete Example

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

entities.ts

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',
  user: 'postgres',
  password: 'password',
  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);

---

Next Steps

• Define Entities: Explore all decorators and type abstractions.
• Define Relations: One-to-one, one-to-many, and many-to-many mappings.
• Querying: Deep selection, filtering, and sorting.
• Transactions: Automatic and manual transaction patterns.
• Migrations: Schema evolution with the CLI and Drift Detection.