@mikro-orm/postgresql 7.0.0-dev.2 → 7.0.0-dev.200

package/PostgreSqlPlatform.js

@@ -1,48 +1,9 @@
 import { Client } from 'pg';
+import array from 'postgres-array';
 import parseDate from 'postgres-date';
 import PostgresInterval from 'postgres-interval';
-import { raw, ALIAS_REPLACEMENT, Utils, Type, RawQueryFragment, } from '@mikro-orm/core';
-import { AbstractSqlPlatform, PostgreSqlNativeQueryBuilder } from '@mikro-orm/knex';
-import { PostgreSqlSchemaHelper } from './PostgreSqlSchemaHelper.js';
-import { PostgreSqlExceptionConverter } from './PostgreSqlExceptionConverter.js';
-import { FullTextType } from './types/FullTextType.js';
-export class PostgreSqlPlatform extends AbstractSqlPlatform {
-    schemaHelper = new PostgreSqlSchemaHelper(this);
-    exceptionConverter = new PostgreSqlExceptionConverter();
-    setConfig(config) {
-        if (config.get('forceUtcTimezone') == null) {
-            config.set('forceUtcTimezone', true);
-        }
-        super.setConfig(config);
-    }
-    createNativeQueryBuilder() {
-        return new PostgreSqlNativeQueryBuilder(this);
-    }
-    usesReturningStatement() {
-        return true;
-    }
-    usesCascadeStatement() {
-        return true;
-    }
-    supportsNativeEnums() {
-        return true;
-    }
-    usesEnumCheckConstraints() {
-        return true;
-    }
-    supportsCustomPrimaryKeyNames() {
-        return true;
-    }
-    getCurrentTimestampSQL(length) {
-        return `current_timestamp(${length})`;
-    }
-    getDateTimeTypeDeclarationSQL(column) {
-        /* v8 ignore next */
-        return 'timestamptz' + (column.length != null ? `(${column.length})` : '');
-    }
-    getDefaultDateTimeLength() {
-        return 6;
-    }
+import { BasePostgreSqlPlatform, Utils } from '@mikro-orm/sql';
+export class PostgreSqlPlatform extends BasePostgreSqlPlatform {
     convertIntervalToJSValue(value) {
         return PostgresInterval(value);
     }
@@ -52,215 +13,13 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         }
         return value;
     }
-    getTimeTypeDeclarationSQL() {
-        return 'time(0)';
-    }
-    getIntegerTypeDeclarationSQL(column) {
-        if (column.autoincrement && !column.generated) {
-            return 'serial';
-        }
-        return 'int';
-    }
-    getBigIntTypeDeclarationSQL(column) {
-        /* v8 ignore next 3 */
-        if (column.autoincrement) {
-            return `bigserial`;
-        }
-        return 'bigint';
-    }
-    getTinyIntTypeDeclarationSQL(column) {
-        return 'smallint';
-    }
-    getUuidTypeDeclarationSQL(column) {
-        return `uuid`;
-    }
-    getFullTextWhereClause(prop) {
-        if (prop.customType instanceof FullTextType) {
-            return `:column: @@ plainto_tsquery('${prop.customType.regconfig}', :query)`;
-        }
-        /* v8 ignore next 3 */
-        if (prop.columnTypes[0] === 'tsvector') {
-            return `:column: @@ plainto_tsquery('simple', :query)`;
-        }
-        return `to_tsvector('simple', :column:) @@ plainto_tsquery('simple', :query)`;
-    }
-    supportsCreatingFullTextIndex() {
-        return true;
-    }
-    getFullTextIndexExpression(indexName, schemaName, tableName, columns) {
-        /* v8 ignore next */
-        const quotedTableName = this.quoteIdentifier(schemaName ? `${schemaName}.${tableName}` : tableName);
-        const quotedColumnNames = columns.map(c => this.quoteIdentifier(c.name));
-        const quotedIndexName = this.quoteIdentifier(indexName);
-        if (columns.length === 1 && columns[0].type === 'tsvector') {
-            return `create index ${quotedIndexName} on ${quotedTableName} using gin(${quotedColumnNames[0]})`;
-        }
-        return `create index ${quotedIndexName} on ${quotedTableName} using gin(to_tsvector('simple', ${quotedColumnNames.join(` || ' ' || `)}))`;
-    }
-    normalizeColumnType(type, options) {
-        const simpleType = this.extractSimpleType(type);
-        if (['int', 'int4', 'integer'].includes(simpleType)) {
-            return this.getIntegerTypeDeclarationSQL({});
-        }
-        if (['bigint', 'int8'].includes(simpleType)) {
-            return this.getBigIntTypeDeclarationSQL({});
-        }
-        if (['smallint', 'int2'].includes(simpleType)) {
-            return this.getSmallIntTypeDeclarationSQL({});
-        }
-        if (['boolean', 'bool'].includes(simpleType)) {
-            return this.getBooleanTypeDeclarationSQL();
-        }
-        if (['varchar', 'character varying'].includes(simpleType)) {
-            return this.getVarcharTypeDeclarationSQL(options);
-        }
-        if (['char', 'bpchar'].includes(simpleType)) {
-            return this.getCharTypeDeclarationSQL(options);
-        }
-        if (['decimal', 'numeric'].includes(simpleType)) {
-            return this.getDecimalTypeDeclarationSQL(options);
-        }
-        if (['interval'].includes(simpleType)) {
-            return this.getIntervalTypeDeclarationSQL(options);
-        }
-        return super.normalizeColumnType(type, options);
-    }
-    getMappedType(type) {
-        switch (this.extractSimpleType(type)) {
-            case 'tsvector': return Type.getType(FullTextType);
-            default: return super.getMappedType(type);
-        }
-    }
-    getRegExpOperator(val, flags) {
-        /* v8 ignore next 3 */
-        if ((val instanceof RegExp && val.flags.includes('i')) || flags?.includes('i')) {
-            return '~*';
-        }
-        return '~';
-    }
-    /* v8 ignore next 8 */
-    getRegExpValue(val) {
-        if (val.flags.includes('i')) {
-            return { $re: val.source, $flags: val.flags };
-        }
-        return { $re: val.source };
-    }
-    isBigIntProperty(prop) {
-        return super.isBigIntProperty(prop) || (['bigserial', 'int8'].includes(prop.columnTypes?.[0]));
-    }
-    getArrayDeclarationSQL() {
-        return 'text[]';
-    }
-    getFloatDeclarationSQL() {
-        return 'real';
-    }
-    getDoubleDeclarationSQL() {
-        return 'double precision';
-    }
-    getEnumTypeDeclarationSQL(column) {
-        /* v8 ignore next 3 */
-        if (column.nativeEnumName) {
-            return column.nativeEnumName;
-        }
-        if (column.items?.every(item => Utils.isString(item))) {
-            return 'text';
-        }
-        return `smallint`;
-    }
-    supportsMultipleStatements() {
-        return true;
-    }
-    getBeginTransactionSQL(options) {
-        if (options?.isolationLevel || options?.readOnly) {
-            let sql = 'start transaction';
-            sql += options.isolationLevel ? ` isolation level ${options.isolationLevel}` : '';
-            sql += options.readOnly ? ` read only` : '';
-            return [sql];
-        }
-        return ['begin'];
-    }
-    marshallArray(values) {
-        const quote = (v) => v === '' || v.match(/["{},\\]/) ? JSON.stringify(v) : v;
-        return `{${values.map(v => quote('' + v)).join(',')}}`;
-    }
     unmarshallArray(value) {
-        if (value === '{}') {
-            return [];
-        }
-        return value.substring(1, value.length - 1).split(',').map(v => {
-            if (v === `""`) {
-                return '';
-            }
-            if (v.match(/"(.*)"/)) {
-                return v.substring(1, v.length - 1).replaceAll('\\"', '"');
-            }
-            return v;
-        });
-    }
-    getVarcharTypeDeclarationSQL(column) {
-        if (column.length === -1) {
-            return 'varchar';
-        }
-        return super.getVarcharTypeDeclarationSQL(column);
-    }
-    getCharTypeDeclarationSQL(column) {
-        if (column.length === -1) {
-            return 'char';
-        }
-        return super.getCharTypeDeclarationSQL(column);
-    }
-    getIntervalTypeDeclarationSQL(column) {
-        return 'interval' + (column.length != null ? `(${column.length})` : '');
-    }
-    getBlobDeclarationSQL() {
-        return 'bytea';
-    }
-    getJsonDeclarationSQL() {
-        return 'jsonb';
-    }
-    getSearchJsonPropertyKey(path, type, aliased, value) {
-        const first = path.shift();
-        const last = path.pop();
-        const root = this.quoteIdentifier(aliased ? `${ALIAS_REPLACEMENT}.${first}` : first);
-        type = typeof type === 'string' ? this.getMappedType(type).runtimeType : String(type);
-        const types = {
-            number: 'float8',
-            bigint: 'int8',
-            boolean: 'bool',
-        };
-        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]))) {
-            lastOperator = '->';
-        }
-        if (path.length === 0) {
-            return cast(`${root}${lastOperator}'${last}'`);
-        }
-        return cast(`${root}->${path.map(a => this.quoteValue(a)).join('->')}${lastOperator}'${last}'`);
-    }
-    getJsonIndexDefinition(index) {
-        return index.columnNames
-            .map(column => {
-            if (!column.includes('.')) {
-                return column;
-            }
-            const path = column.split('.');
-            const first = path.shift();
-            const last = path.pop();
-            if (path.length === 0) {
-                return `(${this.quoteIdentifier(first)}->>${this.quoteValue(last)})`;
-            }
-            return `(${this.quoteIdentifier(first)}->${path.map(c => this.quoteValue(c)).join('->')}->>${this.quoteValue(last)})`;
-        });
-    }
-    quoteIdentifier(id, quote = '"') {
-        if (RawQueryFragment.isKnownFragment(id)) {
-            return super.quoteIdentifier(id);
-        }
-        return `${quote}${id.replace('.', `${quote}.${quote}`)}${quote}`;
+        return array.parse(value);
     }
     escape(value) {
+        if (typeof value === 'bigint') {
+            value = value.toString();
+        }
         if (typeof value === 'string') {
             return Client.prototype.escapeLiteral(value);
         }
@@ -270,104 +29,10 @@ export class PostgreSqlPlatform extends AbstractSqlPlatform {
         if (ArrayBuffer.isView(value)) {
             return `E'\\\\x${value.toString('hex')}'`;
         }
-        return super.escape(value);
-    }
-    pad(number, digits) {
-        return String(number).padStart(digits, '0');
-    }
-    /** @internal */
-    formatDate(date) {
-        if (this.timezone === 'Z') {
-            return date.toISOString();
-        }
-        let offset = -date.getTimezoneOffset();
-        let year = date.getFullYear();
-        const isBCYear = year < 1;
-        /* v8 ignore next 3 */
-        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 */
-        if (offset < 0) {
-            ret += '-';
-            offset *= -1;
-        }
-        else {
-            ret += '+';
-        }
-        ret += this.pad(Math.floor(offset / 60), 2) + ':' + this.pad(offset % 60, 2);
-        /* v8 ignore next 3 */
-        if (isBCYear) {
-            ret += ' BC';
-        }
-        return ret;
-    }
-    indexForeignKeys() {
-        return false;
-    }
-    getDefaultMappedType(type) {
-        const normalizedType = this.extractSimpleType(type);
-        const map = {
-            'int2': 'smallint',
-            'smallserial': 'smallint',
-            'int': 'integer',
-            'int4': 'integer',
-            'serial': 'integer',
-            'serial4': 'integer',
-            'int8': 'bigint',
-            'bigserial': 'bigint',
-            'serial8': 'bigint',
-            'numeric': 'decimal',
-            'bool': 'boolean',
-            'real': 'float',
-            'float4': 'float',
-            'float8': 'double',
-            'timestamp': 'datetime',
-            'timestamptz': 'datetime',
-            'bytea': 'blob',
-            'jsonb': 'json',
-            'character varying': 'varchar',
-            'bpchar': 'character',
-        };
-        return super.getDefaultMappedType(map[normalizedType] ?? type);
-    }
-    supportsSchemas() {
-        return true;
-    }
-    getDefaultSchemaName() {
-        return 'public';
-    }
-    /**
-     * Returns the default name of index for the given columns
-     * cannot go past 63 character length for identifiers in MySQL
-     */
-    getIndexName(tableName, columns, type) {
-        const indexName = super.getIndexName(tableName, columns, type);
-        if (indexName.length > 63) {
-            const suffix = type === 'primary' ? 'pkey' : type;
-            return `${indexName.substring(0, 55 - type.length)}_${Utils.hash(indexName, 5)}_${suffix}`;
-        }
-        return indexName;
-    }
-    getDefaultPrimaryName(tableName, columns) {
-        const indexName = `${tableName}_pkey`;
-        if (indexName.length > 63) {
-            return `${indexName.substring(0, 55 - 'pkey'.length)}_${Utils.hash(indexName, 5)}_pkey`;
-        }
-        return indexName;
-    }
-    /**
-     * @inheritDoc
-     */
-    castColumn(prop) {
-        switch (prop?.columnTypes?.[0]) {
-            case this.getUuidTypeDeclarationSQL({}): return '::text';
-            case this.getBooleanTypeDeclarationSQL(): return '::int';
-            default: return '';
+        if (Array.isArray(value)) {
+            return value.map(v => this.escape(v)).join(', ');
         }
+        return value;
     }
     /**
      * @inheritDoc
@@ -377,19 +42,16 @@ 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;
         }
         return parsed;
     }
-    getDefaultClientUrl() {
-        return 'postgresql://postgres@127.0.0.1:5432';
-    }
 }

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

@@ -1,8 +1,7 @@
-export * from '@mikro-orm/knex';
+export * from '@mikro-orm/sql';
 export * from './PostgreSqlConnection.js';
 export * from './PostgreSqlDriver.js';
 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 { PostgreSqlEntityManager as EntityManager } from './PostgreSqlEntityManager.js';
+export { PostgreSqlMikroORM as MikroORM, type PostgreSqlOptions as Options, definePostgreSqlConfig as defineConfig, } from './PostgreSqlMikroORM.js';
+export { raw } from './raw.js';

package/index.js

@@ -1,8 +1,7 @@
-export * from '@mikro-orm/knex';
+export * from '@mikro-orm/sql';
 export * from './PostgreSqlConnection.js';
 export * from './PostgreSqlDriver.js';
 export * from './PostgreSqlPlatform.js';
-export * from './PostgreSqlSchemaHelper.js';
-export * from './PostgreSqlExceptionConverter.js';
-export * from './types/index.js';
+export { PostgreSqlEntityManager as EntityManager } from './PostgreSqlEntityManager.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.2",
+  "version": "7.0.0-dev.200",
   "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,10 +38,10 @@
   },
   "homepage": "https://mikro-orm.io",
   "engines": {
-    "node": ">= 22.11.0"
+    "node": ">= 22.17.0"
   },
   "scripts": {
-    "build": "yarn clean && yarn compile && yarn copy",
+    "build": "yarn compile && yarn copy",
     "clean": "yarn run -T rimraf ./dist",
     "compile": "yarn run -T tsc -p tsconfig.build.json",
     "copy": "node ../../scripts/copy.mjs"
@@ -50,18 +50,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@mikro-orm/knex": "7.0.0-dev.2",
-    "pg": "8.13.1",
-    "postgres-array": "3.0.2",
+    "@mikro-orm/sql": "7.0.0-dev.200",
+    "kysely": "0.28.10",
+    "pg": "8.18.0",
+    "pg-cursor": "2.17.0",
+    "postgres-array": "3.0.4",
     "postgres-date": "2.1.0",
     "postgres-interval": "4.0.2"
   },
   "devDependencies": {
-    "@mikro-orm/core": "^6.4.5",
-    "kysely": "https://pkg.pr.new/kysely-org/kysely/kysely@2b7007e"
+    "@mikro-orm/core": "^6.6.4"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.0.0-dev.2",
-    "kysely": "*"
+    "@mikro-orm/core": "7.0.0-dev.200"
   }
 }

package/raw.d.ts

@@ -0,0 +1,58 @@
+import { type AnyString, type Dictionary, type EntityKey, type RawQueryFragment, type QueryBuilder } from '@mikro-orm/sql';
+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/sql';
+/**
+ * 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);
+}