> Every UQL docs page, as Markdown: https://uql-orm.dev/llms.txt
> The same docs over MCP: https://uql-orm.dev/mcp
> Before writing UQL code, read the skill: https://uql-orm.dev/.well-known/agent-skills/uql-orm/SKILL.md

# Quick Start

> Install UQL, define an entity, and run your first query.

Source: https://uql-orm.dev/getting-started

[UQL](https://uql-orm.dev/index.md) is a TypeScript ORM whose queries are plain, typed JSON objects. Entities are plain classes, with no code generation. This page takes you from install to a first query.

> **Using a coding agent?**
>
> [Paste the setup prompt](https://uql-orm.dev/ai-agents.md) and it runs these steps in your project, for your runtime and database.

## 1. Install

npm:

```sh
npm install uql-orm pg # or mysql2, better-sqlite3, mongodb, etc.
npm install -D tsx     # the CLI runs uql.config.ts through it on Node
```

bun:

```sh
bun add uql-orm # bun:sql and bun:sqlite need no driver
```

pnpm:

```sh
pnpm add uql-orm pg # or mysql2, better-sqlite3, mongodb, etc.
pnpm add -D tsx     # the CLI runs uql.config.ts through it on Node
```

### Requirements

UQL runs on Node 22.18+, Bun and edge runtimes such as Cloudflare Workers, with TypeScript 5.7 or newer. It is ESM only; a CommonJS app loads it through `require(esm)`. Three `tsconfig.json` settings matter:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "module": "nodenext", // or "preserve": the resolver must read `exports`
    "target": "es2024", // any dated target from es2022; `esnext` leaves decorators untransformed
    "lib": ["esnext"] // `await using` needs `AsyncDisposable`
  }
}
```

Behind a bundler, `"module": "preserve"` (TypeScript 5.4+) or `"moduleResolution": "bundler"` also works. Vite’s template pins `lib` to `ES2023`, so add `esnext`. Next.js needs [a Babel config](https://uql-orm.dev/nextjs.md#decorators) for the decorators. If Node runs your compiled output, set `"type": "module"` in `package.json`.

## 2. Define an entity and a pool

```ts title="entities.ts"
import { Entity, Id, Field } from 'uql-orm';

@Entity()
export class User {
  @Id({ type: 'uuid', onInsert: () => crypto.randomUUID() })
  id!: string;

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

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

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

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

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

Create the pool once per process and import it everywhere. It connects on the first query. Other databases and pool sizing are in [Pool](https://uql-orm.dev/pool.md).

## 3. Create the table

```sh
npx uql-migrate sync
```

`sync` compares the `entities` in `uql.config.ts` with the database and creates what is missing. Add `--dry-run` to print the DDL instead. Once the data matters, switch to [`generate:entities`](https://uql-orm.dev/migrations.md#from-entities-to-the-database), which writes the diff to a migration you review. For tables that already exist, [`generate:from-db`](https://uql-orm.dev/migrations.md#from-a-database-to-entities) writes the entities.

## 4. Query

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

await pool.insertMany(User, [
  { email: 'ada@uql-orm.dev', name: 'Ada' },
  { email: 'grace@example.com', name: 'Grace' },
]);

const users = await pool.findMany(User, {
  $select: { id: true, name: true },
  $where: { email: { $endsWith: '@uql-orm.dev' } },
});
// [{ id: '...', name: 'Ada' }]
```

Each pool call takes a connection and releases it. To share one connection across calls, use `pool.withQuerier`, or [`pool.transaction`](https://uql-orm.dev/querying/transactions.md) to commit them together. See [pool vs. querier](https://uql-orm.dev/querying/querier.md#choosing-poolx-vs-querierx).

## Next steps

- [Entities](https://uql-orm.dev/entities/basic.md) and [relations](https://uql-orm.dev/entities/relations.md)
- [Querying](https://uql-orm.dev/querying/querier.md) and [transactions](https://uql-orm.dev/querying/transactions.md)
- [Migrations](https://uql-orm.dev/migrations.md) and drift detection
- [Examples](https://github.com/rogerpadilla/uql/tree/main/examples): runnable apps on Node, Bun, Next.js and Cloudflare D1