{"id":16696,"library":"uql-orm","title":"UQL ORM","description":"UQL ORM is a fast, type-safe TypeScript Object-Relational Mapper (ORM) designed with a JSON-native query protocol. Currently at version 0.9.0, it aims for universal compatibility, running across Node.js, Bun, Deno, Cloudflare Workers, Electron, React Native, and browsers. It provides a unified API for various SQL and NoSQL databases, including PostgreSQL, MySQL, MariaDB, SQLite, LibSQL, Neon, D1, and MongoDB. Key differentiators include 100% serializable queries, deeply type-safe APIs for intelligent auto-completion, multi-level operators, and robust support for advanced features like semantic search. While still pre-1.0, the project shows active development with frequent updates and a strong focus on performance and developer experience, offering both decorator-based and imperative entity definition styles.","status":"active","version":"0.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/rogerpadilla/uql","tags":["javascript","orm","query-builder","data-mapper","persistence","database","db","typesafe","typescript-orm","typescript"],"install":[{"cmd":"npm install uql-orm","lang":"bash","label":"npm"},{"cmd":"yarn add uql-orm","lang":"bash","label":"yarn"},{"cmd":"pnpm add uql-orm","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for connecting to LibSQL / Turso databases.","package":"@libsql/client","optional":true},{"reason":"Required for connecting to Neon serverless PostgreSQL databases.","package":"@neondatabase/serverless","optional":true},{"reason":"Required for connecting to SQLite databases.","package":"better-sqlite3","optional":true},{"reason":"Required for the 'uql-orm/express' middleware, which provides auto-generated REST APIs.","package":"express","optional":true},{"reason":"Required for connecting to MariaDB databases (dedicated driver).","package":"mariadb","optional":true},{"reason":"Required for connecting to MongoDB databases.","package":"mongodb","optional":true},{"reason":"Required for connecting to MySQL and MariaDB databases.","package":"mysql2","optional":true},{"reason":"Required for connecting to PostgreSQL, CockroachDB, and Neon databases.","package":"pg","optional":true},{"reason":"Provides streaming capabilities for PostgreSQL queries, often used with 'pg'.","package":"pg-query-stream","optional":true}],"imports":[{"note":"These are core decorators for defining entities, IDs, and fields. Requires 'experimentalDecorators' and 'emitDecoratorMetadata' in tsconfig.json if not using 'defineEntity'.","wrong":"import * as uql from 'uql-orm'; // Then uql.Entity","symbol":"{ Entity, Id, Field }","correct":"import { Entity, Id, Field } from 'uql-orm';"},{"note":"Introduced in v0.8.0, this imperative API allows defining entities without decorators, bypassing tsconfig.json requirements. UQL is Pure ESM, so `require` is generally incorrect.","wrong":"const defineEntity = require('uql-orm').defineEntity;","symbol":"defineEntity","correct":"import { defineEntity } from 'uql-orm';"},{"note":"Database-specific querier pools are imported from subpaths (e.g., '/postgres', '/mysql', '/mongo') to keep bundles lean.","wrong":"import { PgQuerierPool } from 'uql-orm';","symbol":"PgQuerierPool","correct":"import { PgQuerierPool } from 'uql-orm/postgres';"},{"note":"Utility type used for defining relationships between entities, preventing TypeScript circular dependency errors. Use `import type` for type-only imports.","wrong":"import { Relation } from 'uql-orm';","symbol":"type Relation","correct":"import { type Relation } from 'uql-orm';"}],"quickstart":{"code":"import { Entity, Id, Field } from 'uql-orm';\nimport { PgQuerierPool } from 'uql-orm/postgres';\n\n// 1. Define your Entity (User.ts)\n@Entity()\nexport class User {\n  @Id({ type: 'uuid' })\n  id?: string;\n\n  @Field({ unique: true })\n  email?: string;\n\n  @Field()\n  name?: string;\n}\n\n// 2. Set up the Pool and Query (app.ts)\nasync function runQuery() {\n  const pool = new PgQuerierPool({\n    host: process.env.DB_HOST ?? 'localhost',\n    port: parseInt(process.env.DB_PORT ?? '5432', 10),\n    database: process.env.DB_NAME ?? 'app_db',\n    user: process.env.DB_USER ?? 'postgres',\n    password: process.env.DB_PASSWORD ?? 'password',\n  });\n\n  try {\n    await pool.withQuerier(async (querier) => {\n      // Ensure schema is in sync (for development/testing)\n      // In production, use migrations CLI\n      await querier.sync(User, { drop: true }); // DANGER: drops table\n\n      // Create a user\n      const newUser = await querier.createOne(User, { email: 'test@example.com', name: 'John Doe' });\n      console.log('Created user:', newUser);\n\n      // Find users\n      const users = await querier.findMany(User, {\n        $where: { name: { $istartsWith: 'John' } },\n        $select: { id: true, email: true },\n      });\n      console.log('Found users:', users);\n    });\n  } catch (error) {\n    console.error('Database operation failed:', error);\n  } finally {\n    await pool.end(); // Don't forget to release connections\n  }\n}\n\nrunQuery();\n\n// tsconfig.json configuration for decorators:\n// {\n//   \"compilerOptions\": {\n//     \"experimentalDecorators\": true,\n//     \"emitDecoratorMetadata\": true,\n//     \"moduleResolution\": \"NodeNext\",\n//     \"module\": \"NodeNext\",\n//     \"target\": \"ES2022\"\n//   }\n// }","lang":"typescript","description":"This quickstart demonstrates defining a User entity with decorators, connecting to a PostgreSQL database using a querier pool, syncing the schema (caution: drops table), creating a new user, and performing a filtered query to fetch users by name. It also highlights necessary TypeScript compiler options."},"warnings":[{"fix":"Consult the official UQL documentation and release notes for migration guides when updating. Pin exact versions in production (`~0.x.y` rather than `^0.x.y`).","message":"UQL is currently pre-1.0 (v0.9.0), meaning API surfaces may evolve rapidly and introduce breaking changes in minor versions. Always review release notes when upgrading to new 0.x.x versions.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Add or ensure the following in `compilerOptions` in your `tsconfig.json`: `{ \"experimentalDecorators\": true, \"emitDecoratorMetadata\": true }`. Alternatively, use the imperative `defineEntity` API which does not require these flags.","message":"If using TypeScript decorators for entity definition (e.g., `@Entity`, `@Field`), your `tsconfig.json` must have `\"experimentalDecorators\": true` and `\"emitDecoratorMetadata\": true` enabled. Failure to do so will result in decorators being ignored or runtime errors due to missing metadata.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure your `tsconfig.json` (for TypeScript) or `package.json` (for Node.js) specifies ESM. For TypeScript, set `\"module\": \"NodeNext\"`, `\"moduleResolution\": \"NodeNext\"`, `\"target\": \"ES2022\"` or similar. For Node.js, ensure `\"type\": \"module\"` in `package.json` or use `.mjs` file extensions.","message":"UQL is a Pure ESM (ECMAScript Module) package. Using CommonJS `require()` statements to import UQL modules will lead to import errors. Your project's module resolution must be configured for ESM.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Install the appropriate driver package(s) for your chosen database(s). For example, `npm install uql-orm pg` for PostgreSQL.","message":"Database drivers (e.g., `pg`, `mysql2`, `better-sqlite3`, `mongodb`) are peer dependencies and must be installed separately alongside `uql-orm`. UQL does not bundle these drivers.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"For new projects or if encountering decorator issues, consider using the `defineEntity` API. For existing projects relying on decorators, ensure your `tsconfig.json` is correctly configured as per `tsconfig.json` warnings.","message":"Prior to v0.8.0, entity definitions in UQL were exclusively decorator-based, which required specific TypeScript compiler flags (`experimentalDecorators`). Version 0.8.0 introduced the `defineEntity` API as an alternative, decoupling entity metadata from class definitions and making decorators optional. This was a significant shift for projects constrained by decorator support.","severity":"breaking","affected_versions":"<0.8.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Add `\"experimentalDecorators\": true` and `\"emitDecoratorMetadata\": true` to your `tsconfig.json` under `compilerOptions`.","cause":"TypeScript compiler options are not set for decorator processing.","error":"Decorators not working: Ensure experimentalDecorators and emitDecoratorMetadata are enabled in tsconfig.json"},{"fix":"Configure your project to use ECMAScript Modules (ESM). For TypeScript, set `\"module\": \"NodeNext\"` and `\"moduleResolution\": \"NodeNext\"` in `tsconfig.json`. For Node.js, ensure `\"type\": \"module\"` in `package.json`.","cause":"Attempting to import UQL in a CommonJS environment or with incorrect module resolution settings.","error":"ESM import issues: UQL is Pure ESM — set your module to NodeNext, ESNext, or Bundler"},{"fix":"Verify all connection parameters (host, port, user, password, database). Ensure you have installed the correct database driver (e.g., `npm install pg` for PostgreSQL) and that its version is compatible with your Node.js runtime and UQL.","cause":"Incorrect database connection string, invalid credentials, or the required database driver package is missing or incompatible.","error":"Connection errors: Double-check database credentials and that your driver package (for example pg, mysql2, or better-sqlite3) is installed and compatible with your runtime."},{"fix":"Ensure `\"emitDecoratorMetadata\": true` is set in your `tsconfig.json` under `compilerOptions`.","cause":"This error often occurs when decorators are used, but `emitDecoratorMetadata` is not enabled, leading to missing type metadata at runtime.","error":"TypeError: Cannot read properties of undefined (reading 'constructor') at Reflect.getMetadata"}],"ecosystem":"npm"}