@mikro-orm/postgresql 7.0.0-dev.9 → 7.0.0-dev.91

package/PostgreSqlConnection.js

@@ -1,5 +1,5 @@
-import TypeOverrides from 'pg/lib/type-overrides.js';
-import { Pool } from 'pg';
+import { Pool, TypeOverrides } from 'pg';
+import Cursor from 'pg-cursor';
 import { PostgresDialect } from 'kysely';
 import array from 'postgres-array';
 import { AbstractSqlConnection, Utils } from '@mikro-orm/knex';
@@ -8,6 +8,7 @@ export class PostgreSqlConnection extends AbstractSqlConnection {
         const options = this.mapOptions(overrides);
         return new PostgresDialect({
             pool: new Pool(options),
+            cursor: Cursor,
             onCreateConnection: this.options.onCreateConnection ?? this.config.get('onCreateConnection'),
         });
     }

package/PostgreSqlExceptionConverter.d.ts

@@ -1,8 +1,8 @@
 import { ExceptionConverter, type Dictionary, type DriverException } from '@mikro-orm/core';
 export declare class PostgreSqlExceptionConverter extends ExceptionConverter {
     /**
-     * @link http://www.postgresql.org/docs/9.4/static/errcodes-appendix.html
-     * @link https://github.com/doctrine/dbal/blob/master/src/Driver/AbstractPostgreSQLDriver.php
+     * @see http://www.postgresql.org/docs/9.4/static/errcodes-appendix.html
+     * @see https://github.com/doctrine/dbal/blob/master/src/Driver/AbstractPostgreSQLDriver.php
      */
     convertException(exception: Error & Dictionary): DriverException;
 }

package/PostgreSqlExceptionConverter.js

@@ -1,8 +1,8 @@
 import { DeadlockException, ExceptionConverter, ForeignKeyConstraintViolationException, InvalidFieldNameException, NonUniqueFieldNameException, NotNullConstraintViolationException, SyntaxErrorException, TableExistsException, TableNotFoundException, UniqueConstraintViolationException, CheckConstraintViolationException, } from '@mikro-orm/core';
 export class PostgreSqlExceptionConverter extends ExceptionConverter {
     /**
-     * @link http://www.postgresql.org/docs/9.4/static/errcodes-appendix.html
-     * @link https://github.com/doctrine/dbal/blob/master/src/Driver/AbstractPostgreSQLDriver.php
+     * @see http://www.postgresql.org/docs/9.4/static/errcodes-appendix.html
+     * @see https://github.com/doctrine/dbal/blob/master/src/Driver/AbstractPostgreSQLDriver.php
      */
     convertException(exception) {
         if (exception.detail?.toString().trim()) {
@@ -11,7 +11,7 @@ export class PostgreSqlExceptionConverter extends ExceptionConverter {
         if (exception.hint?.toString().trim()) {
             exception.message += '\n - hint: ' + exception.hint;
         }
-        /* v8 ignore start */
+        /* v8 ignore next */
         switch (exception.code) {
             case '40001':
             case '40P01':
@@ -42,7 +42,6 @@ export class PostgreSqlExceptionConverter extends ExceptionConverter {
             case '42P07':
                 return new TableExistsException(exception);
         }
-        /* v8 ignore stop */
         return super.convertException(exception);
     }
 }

package/PostgreSqlMikroORM.d.ts

@@ -1,19 +1,18 @@
-import { MikroORM, type Options, type IDatabaseDriver, type EntityManager, type EntityManagerType } from '@mikro-orm/core';
-import { PostgreSqlDriver } from './PostgreSqlDriver.js';
+import { type AnyEntity, type EntityClass, type EntitySchema, MikroORM, type Options, type IDatabaseDriver, type EntityManager, type EntityManagerType } from '@mikro-orm/core';
 import type { SqlEntityManager } from '@mikro-orm/knex';
+import { PostgreSqlDriver } from './PostgreSqlDriver.js';
+export type PostgreSqlOptions<EM extends SqlEntityManager<PostgreSqlDriver> = SqlEntityManager<PostgreSqlDriver>, Entities extends (string | EntityClass<AnyEntity> | EntitySchema)[] = (string | EntityClass<AnyEntity> | EntitySchema)[]> = Options<PostgreSqlDriver, EM, Entities>;
+export declare function definePostgreSqlConfig<EM extends SqlEntityManager<PostgreSqlDriver> = SqlEntityManager<PostgreSqlDriver>, Entities extends (string | EntityClass<AnyEntity> | EntitySchema)[] = (string | EntityClass<AnyEntity> | EntitySchema)[]>(options: Options<PostgreSqlDriver, EM, Entities>): Options<PostgreSqlDriver, EM, Entities>;
 /**
  * @inheritDoc
  */
-export declare class PostgreSqlMikroORM<EM extends EntityManager = SqlEntityManager> extends MikroORM<PostgreSqlDriver, EM> {
-    private static DRIVER;
+export declare class PostgreSqlMikroORM<EM extends SqlEntityManager<PostgreSqlDriver> = SqlEntityManager<PostgreSqlDriver>, Entities extends (string | EntityClass<AnyEntity> | EntitySchema)[] = (string | EntityClass<AnyEntity> | EntitySchema)[]> extends MikroORM<PostgreSqlDriver, EM, Entities> {
     /**
      * @inheritDoc
      */
-    static init<D extends IDatabaseDriver = PostgreSqlDriver, EM extends EntityManager = D[typeof EntityManagerType] & EntityManager>(options?: Options<D, EM>): Promise<MikroORM<D, EM>>;
+    static init<D extends IDatabaseDriver = PostgreSqlDriver, EM extends EntityManager<D> = D[typeof EntityManagerType] & EntityManager<D>, Entities extends (string | EntityClass<AnyEntity> | EntitySchema)[] = (string | EntityClass<AnyEntity> | EntitySchema)[]>(options: Options<D, EM, Entities>): Promise<MikroORM<D, EM, Entities>>;
     /**
      * @inheritDoc
      */
-    static initSync<D extends IDatabaseDriver = PostgreSqlDriver, EM extends EntityManager = D[typeof EntityManagerType] & EntityManager>(options: Options<D, EM>): MikroORM<D, EM>;
+    constructor(options: Options<PostgreSqlDriver, EM, Entities>);
 }
-export type PostgreSqlOptions = Options<PostgreSqlDriver>;
-export declare function definePostgreSqlConfig(options: PostgreSqlOptions): Options<PostgreSqlDriver, SqlEntityManager<PostgreSqlDriver> & EntityManager<IDatabaseDriver<import("@mikro-orm/core").Connection>>>;

package/PostgreSqlMikroORM.js

@@ -1,24 +1,22 @@
 import { defineConfig, MikroORM, } from '@mikro-orm/core';
 import { PostgreSqlDriver } from './PostgreSqlDriver.js';
+export function definePostgreSqlConfig(options) {
+    return defineConfig({ driver: PostgreSqlDriver, ...options });
+}
 /**
  * @inheritDoc
  */
 export class PostgreSqlMikroORM extends MikroORM {
-    static DRIVER = PostgreSqlDriver;
     /**
      * @inheritDoc
      */
     static async init(options) {
-        return super.init(options);
+        return super.init(definePostgreSqlConfig(options));
     }
     /**
      * @inheritDoc
      */
-    static initSync(options) {
-        return super.initSync(options);
+    constructor(options) {
+        super(definePostgreSqlConfig(options));
     }
 }
-/* v8 ignore next 3 */
-export function definePostgreSqlConfig(options) {
-    return defineConfig({ driver: PostgreSqlDriver, ...options });
-}

package/PostgreSqlPlatform.d.ts

@@ -1,5 +1,5 @@
 import { type IPostgresInterval } from 'postgres-interval';
-import { type IsolationLevel, type EntityProperty, Type, type SimpleColumnMeta, type Configuration } from '@mikro-orm/core';
+import { type Configuration, type EntityProperty, type IsolationLevel, type SimpleColumnMeta, Type } from '@mikro-orm/core';
 import { AbstractSqlPlatform, type IndexDef, PostgreSqlNativeQueryBuilder } from '@mikro-orm/knex';
 import { PostgreSqlSchemaHelper } from './PostgreSqlSchemaHelper.js';
 import { PostgreSqlExceptionConverter } from './PostgreSqlExceptionConverter.js';
@@ -81,7 +81,9 @@ export declare class PostgreSqlPlatform extends AbstractSqlPlatform {
     getJsonDeclarationSQL(): string;
     getSearchJsonPropertyKey(path: string[], type: string | undefined | Type, aliased: boolean, value?: unknown): string;
     getJsonIndexDefinition(index: IndexDef): string[];
-    quoteIdentifier(id: string, quote?: string): string;
+    quoteIdentifier(id: string | {
+        toString: () => string;
+    }, quote?: string): string;
     escape(value: any): string;
     private pad;
     /** @internal */

package/PostgreSqlPlatform.js

@@ -1,7 +1,7 @@
 import { Client } from 'pg';
 import parseDate from 'postgres-date';
 import PostgresInterval from 'postgres-interval';
-import { raw, ALIAS_REPLACEMENT, Utils, Type, RawQueryFragment, } from '@mikro-orm/core';
+import { ALIAS_REPLACEMENT, ARRAY_OPERATORS, raw, RawQueryFragment, Type, Utils, } from '@mikro-orm/core';
 import { AbstractSqlPlatform, PostgreSqlNativeQueryBuilder } from '@mikro-orm/knex';
 import { PostgreSqlSchemaHelper } from './PostgreSqlSchemaHelper.js';
 import { PostgreSqlExceptionConverter } from './PostgreSqlExceptionConverter.js';
@@ -62,7 +62,7 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         return 'int';
     }
     getBigIntTypeDeclarationSQL(column) {
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (column.autoincrement) {
             return `bigserial`;
         }
@@ -78,7 +78,7 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         if (prop.customType instanceof FullTextType) {
             return `:column: @@ plainto_tsquery('${prop.customType.regconfig}', :query)`;
         }
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (prop.columnTypes[0] === 'tsvector') {
             return `:column: @@ plainto_tsquery('simple', :query)`;
         }
@@ -132,13 +132,13 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         }
     }
     getRegExpOperator(val, flags) {
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if ((val instanceof RegExp && val.flags.includes('i')) || flags?.includes('i')) {
             return '~*';
         }
         return '~';
     }
-    /* v8 ignore next 8 */
+    /* v8 ignore next */
     getRegExpValue(val) {
         if (val.flags.includes('i')) {
             return { $re: val.source, $flags: val.flags };
@@ -158,11 +158,11 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         return 'double precision';
     }
     getEnumTypeDeclarationSQL(column) {
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (column.nativeEnumName) {
             return column.nativeEnumName;
         }
-        if (column.items?.every(item => Utils.isString(item))) {
+        if (column.items?.every(item => typeof item === 'string')) {
             return 'text';
         }
         return `smallint`;
@@ -231,7 +231,7 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         const cast = (key) => raw(type in types ? `(${key})::${types[type]}` : key);
         let lastOperator = '->>';
         // force `->` for operator payloads with array values
-        if (Utils.isPlainObject(value) && Object.keys(value).every(key => Utils.isArrayOperator(key) && Array.isArray(value[key]))) {
+        if (Utils.isPlainObject(value) && Object.keys(value).every(key => ARRAY_OPERATORS.includes(key) && Array.isArray(value[key]))) {
             lastOperator = '->';
         }
         if (path.length === 0) {
@@ -258,7 +258,7 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         if (RawQueryFragment.isKnownFragment(id)) {
             return super.quoteIdentifier(id);
         }
-        return `${quote}${id.replace('.', `${quote}.${quote}`)}${quote}`;
+        return `${quote}${id.toString().replace('.', `${quote}.${quote}`)}${quote}`;
     }
     escape(value) {
         if (typeof value === 'string') {
@@ -270,6 +270,9 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         if (ArrayBuffer.isView(value)) {
             return `E'\\\\x${value.toString('hex')}'`;
         }
+        if (Array.isArray(value)) {
+            return value.map(v => this.escape(v)).join(', ');
+        }
         return super.escape(value);
     }
     pad(number, digits) {
@@ -283,14 +286,14 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         let offset = -date.getTimezoneOffset();
         let year = date.getFullYear();
         const isBCYear = year < 1;
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (isBCYear) {
             year = Math.abs(year) + 1;
         }
         const datePart = `${this.pad(year, 4)}-${this.pad(date.getMonth() + 1, 2)}-${this.pad(date.getDate(), 2)}`;
         const timePart = `${this.pad(date.getHours(), 2)}:${this.pad(date.getMinutes(), 2)}:${this.pad(date.getSeconds(), 2)}.${this.pad(date.getMilliseconds(), 3)}`;
         let ret = `${datePart}T${timePart}`;
-        /* v8 ignore next 4 */
+        /* v8 ignore next */
         if (offset < 0) {
             ret += '-';
             offset *= -1;
@@ -299,7 +302,7 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
             ret += '+';
         }
         ret += this.pad(Math.floor(offset / 60), 2) + ':' + this.pad(offset % 60, 2);
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (isBCYear) {
             ret += ' BC';
         }
@@ -377,13 +380,13 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         if (typeof value === 'string' && value.charAt(10) === 'T') {
             return new Date(value);
         }
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (typeof value === 'number') {
             return new Date(value);
         }
         // @ts-ignore fix wrong type resolution during build
         const parsed = parseDate(value);
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (parsed === null) {
             return value;
         }

package/PostgreSqlSchemaHelper.js

@@ -68,7 +68,9 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             const table = schema.addTable(t.table_name, t.schema_name, t.table_comment);
             const pks = await this.getPrimaryKeys(connection, indexes[key], table.name, table.schema);
             const enums = this.getEnumDefinitions(checks[key] ?? []);
-            table.init(columns[key], indexes[key], checks[key], pks, fks[key], enums);
+            if (columns[key]) {
+                table.init(columns[key], indexes[key], checks[key], pks, fks[key], enums);
+            }
         }
     }
     async getAllIndexes(connection, tables) {
@@ -211,7 +213,7 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             if (match) {
                 return match[1];
             }
-            /* v8 ignore next 8 */
+            /* v8 ignore next */
             switch (value) {
                 case 'r': return 'RESTRICT';
                 case 'c': return 'CASCADE';
@@ -303,7 +305,7 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             if (item.columnName && m1 && m2) {
                 const m3 = m2[1].match(/('[^']*'::text)/g);
                 let items;
-                /* v8 ignore next 5 */
+                /* v8 ignore next */
                 if (m3) {
                     items = m3.map((item) => item.trim().match(/^\(?'(.*)'/)?.[1]);
                 }
@@ -321,7 +323,8 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
         }, {});
     }
     createTableColumn(column, table) {
-        const compositePK = table.getPrimaryKey()?.composite;
+        const pk = table.getPrimaryKey();
+        const compositePK = pk?.composite;
         const primaryKey = !this.hasNonDefaultPrimaryKeyName(table);
         const col = [this.quote(column.name)];
         if (column.autoincrement && !column.generated && !compositePK) {
@@ -351,7 +354,7 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             Utils.runIfNotEmpty(() => col.push('null'), column.nullable);
             Utils.runIfNotEmpty(() => col.push('not null'), !column.nullable);
         }
-        if (column.autoincrement && !column.generated && !compositePK) {
+        if (column.autoincrement && !compositePK) {
             Utils.runIfNotEmpty(() => col.push('primary key'), primaryKey && column.primary);
         }
         const useDefault = column.default != null && column.default !== 'null' && !column.autoincrement;

package/README.md

@@ -11,7 +11,6 @@ TypeScript ORM for Node.js based on Data Mapper, [Unit of Work](https://mikro-or
 [![Chat on discord](https://img.shields.io/discord/1214904142443839538?label=discord&color=blue)](https://discord.gg/w8bjxFHS7X)
 [![Downloads](https://img.shields.io/npm/dm/@mikro-orm/core.svg)](https://www.npmjs.com/package/@mikro-orm/core)
 [![Coverage Status](https://img.shields.io/coveralls/mikro-orm/mikro-orm.svg)](https://coveralls.io/r/mikro-orm/mikro-orm?branch=master)
-[![Maintainability](https://api.codeclimate.com/v1/badges/27999651d3adc47cfa40/maintainability)](https://codeclimate.com/github/mikro-orm/mikro-orm/maintainability)
 [![Build Status](https://github.com/mikro-orm/mikro-orm/workflows/tests/badge.svg?branch=master)](https://github.com/mikro-orm/mikro-orm/actions?workflow=tests)
 
 ## 🤔 Unit of What?
@@ -141,7 +140,7 @@ There is also auto-generated [CHANGELOG.md](CHANGELOG.md) file based on commit m
 - [Composite and Foreign Keys as Primary Key](https://mikro-orm.io/docs/composite-keys)
 - [Filters](https://mikro-orm.io/docs/filters)
 - [Using `QueryBuilder`](https://mikro-orm.io/docs/query-builder)
-- [Preloading Deeply Nested Structures via populate](https://mikro-orm.io/docs/nested-populate)
+- [Populating relations](https://mikro-orm.io/docs/populating-relations)
 - [Property Validation](https://mikro-orm.io/docs/property-validation)
 - [Lifecycle Hooks](https://mikro-orm.io/docs/events#hooks)
 - [Vanilla JS Support](https://mikro-orm.io/docs/usage-with-js)
@@ -382,6 +381,8 @@ See also the list of contributors who [participated](https://github.com/mikro-or
 
 Please ⭐️ this repository if this project helped you!
 
+> If you'd like to support my open-source work, consider sponsoring me directly at [github.com/sponsors/b4nan](https://github.com/sponsors/b4nan).
+
 ## 📝 License
 
 Copyright © 2018 [Martin Adámek](https://github.com/b4nan).

package/index.d.ts

@@ -5,4 +5,5 @@ export * from './PostgreSqlPlatform.js';
 export * from './PostgreSqlSchemaHelper.js';
 export * from './PostgreSqlExceptionConverter.js';
 export * from './types/index.js';
-export { PostgreSqlMikroORM as MikroORM, PostgreSqlOptions as Options, definePostgreSqlConfig as defineConfig, } from './PostgreSqlMikroORM.js';
+export { PostgreSqlMikroORM as MikroORM, type PostgreSqlOptions as Options, definePostgreSqlConfig as defineConfig, } from './PostgreSqlMikroORM.js';
+export { raw } from './raw.js';

package/index.js

@@ -6,3 +6,4 @@ export * from './PostgreSqlSchemaHelper.js';
 export * from './PostgreSqlExceptionConverter.js';
 export * from './types/index.js';
 export { PostgreSqlMikroORM as MikroORM, definePostgreSqlConfig as defineConfig, } from './PostgreSqlMikroORM.js';
+export { raw } from './raw.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mikro-orm/postgresql",
   "type": "module",
-  "version": "7.0.0-dev.9",
+  "version": "7.0.0-dev.91",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "exports": {
     "./package.json": "./package.json",
@@ -38,7 +38,7 @@
   },
   "homepage": "https://mikro-orm.io",
   "engines": {
-    "node": ">= 22.11.0"
+    "node": ">= 22.17.0"
   },
   "scripts": {
     "build": "yarn clean && yarn compile && yarn copy",
@@ -50,18 +50,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@mikro-orm/knex": "7.0.0-dev.9",
-    "pg": "8.14.1",
+    "@mikro-orm/knex": "7.0.0-dev.91",
+    "pg": "8.16.3",
+    "pg-cursor": "2.15.3",
     "postgres-array": "3.0.4",
     "postgres-date": "2.1.0",
     "postgres-interval": "4.0.2"
   },
   "devDependencies": {
-    "@mikro-orm/core": "^6.4.13",
-    "kysely": "0.28.0"
+    "@mikro-orm/core": "^6.6.2",
+    "kysely": "0.28.8"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.0.0-dev.9",
+    "@mikro-orm/core": "7.0.0-dev.91",
     "kysely": "*"
   }
 }

package/raw.d.ts

@@ -0,0 +1,58 @@
+import { type AnyString, type Dictionary, type EntityKey, type RawQueryFragment, type QueryBuilder } from '@mikro-orm/knex';
+import type { SelectQueryBuilder } from 'kysely';
+/**
+ * Creates raw SQL query fragment that can be assigned to a property or part of a filter. This fragment is represented
+ * by `RawQueryFragment` class instance that can be serialized to a string, so it can be used both as an object value
+ * and key. When serialized, the fragment key gets cached and only such cached key will be recognized by the ORM.
+ * This adds a runtime safety to the raw query fragments.
+ *
+ * > **`raw()` helper is required since v6 to use a raw fragment in your query, both through EntityManager and QueryBuilder.**
+ *
+ * ```ts
+ * // as a value
+ * await em.find(User, { time: raw('now()') });
+ *
+ * // as a key
+ * await em.find(User, { [raw('lower(name)')]: name.toLowerCase() });
+ *
+ * // value can be empty array
+ * await em.find(User, { [raw('(select 1 = 1)')]: [] });
+ * ```
+ *
+ * The `raw` helper supports several signatures, you can pass in a callback that receives the current property alias:
+ *
+ * ```ts
+ * await em.find(User, { [raw(alias => `lower(${alias}.name)`)]: name.toLowerCase() });
+ * ```
+ *
+ * You can also use the `sql` tagged template function, which works the same, but supports only the simple string signature:
+ *
+ * ```ts
+ * await em.find(User, { [sql`lower(name)`]: name.toLowerCase() });
+ * ```
+ *
+ * When using inside filters, you might have to use a callback signature to create new raw instance for every filter usage.
+ *
+ * ```ts
+ * @Filter({ name: 'long', cond: () => ({ [raw('length(perex)')]: { $gt: 10000 } }) })
+ * ```
+ *
+ * The `raw` helper can be used within indexes and uniques to write database-agnostic SQL expressions. In that case, you can use `'??'` to tag your database identifiers (table name, column names, index name, ...) inside your expression, and pass those identifiers as a second parameter to the `raw` helper. Internally, those will automatically be quoted according to the database in use:
+ *
+ * ```ts
+ * // On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("country")
+ * // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`country`)
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => raw(`create index ?? on ?? (??)`, ['custom_idx_on_name', table, columns.name]) })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ *
+ * You can also use the `quote` tag function to write database-agnostic SQL expressions. The end-result is the same as using the `raw` function regarding database identifiers quoting, only to have a more elegant expression syntax:
+ *
+ * ```ts
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ */
+export declare function raw<T extends object = any, R = any>(sql: SelectQueryBuilder<any, any, any> | QueryBuilder<T> | EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): NoInfer<R>;

package/raw.js

@@ -0,0 +1,64 @@
+import { raw as raw_, Utils } from '@mikro-orm/knex';
+/**
+ * Creates raw SQL query fragment that can be assigned to a property or part of a filter. This fragment is represented
+ * by `RawQueryFragment` class instance that can be serialized to a string, so it can be used both as an object value
+ * and key. When serialized, the fragment key gets cached and only such cached key will be recognized by the ORM.
+ * This adds a runtime safety to the raw query fragments.
+ *
+ * > **`raw()` helper is required since v6 to use a raw fragment in your query, both through EntityManager and QueryBuilder.**
+ *
+ * ```ts
+ * // as a value
+ * await em.find(User, { time: raw('now()') });
+ *
+ * // as a key
+ * await em.find(User, { [raw('lower(name)')]: name.toLowerCase() });
+ *
+ * // value can be empty array
+ * await em.find(User, { [raw('(select 1 = 1)')]: [] });
+ * ```
+ *
+ * The `raw` helper supports several signatures, you can pass in a callback that receives the current property alias:
+ *
+ * ```ts
+ * await em.find(User, { [raw(alias => `lower(${alias}.name)`)]: name.toLowerCase() });
+ * ```
+ *
+ * You can also use the `sql` tagged template function, which works the same, but supports only the simple string signature:
+ *
+ * ```ts
+ * await em.find(User, { [sql`lower(name)`]: name.toLowerCase() });
+ * ```
+ *
+ * When using inside filters, you might have to use a callback signature to create new raw instance for every filter usage.
+ *
+ * ```ts
+ * @Filter({ name: 'long', cond: () => ({ [raw('length(perex)')]: { $gt: 10000 } }) })
+ * ```
+ *
+ * The `raw` helper can be used within indexes and uniques to write database-agnostic SQL expressions. In that case, you can use `'??'` to tag your database identifiers (table name, column names, index name, ...) inside your expression, and pass those identifiers as a second parameter to the `raw` helper. Internally, those will automatically be quoted according to the database in use:
+ *
+ * ```ts
+ * // On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("country")
+ * // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`country`)
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => raw(`create index ?? on ?? (??)`, ['custom_idx_on_name', table, columns.name]) })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ *
+ * You can also use the `quote` tag function to write database-agnostic SQL expressions. The end-result is the same as using the `raw` function regarding database identifiers quoting, only to have a more elegant expression syntax:
+ *
+ * ```ts
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ */
+export function raw(sql, params) {
+    if (Utils.isObject(sql) && 'compile' in sql) {
+        const query = sql.compile();
+        const processed = query.sql.replaceAll(/\$\d+/g, '?');
+        return raw_(processed, query.parameters);
+    }
+    return raw_(sql, params);
+}