@mikro-orm/sql 7.0.0-rc.1 → 7.0.0-rc.3

package/dialects/sqlite/SqliteDriver.js

@@ -0,0 +1,14 @@
+import { AbstractSqlDriver } from '../../AbstractSqlDriver.js';
+import { BaseSqliteConnection } from './BaseSqliteConnection.js';
+import { SqlitePlatform } from './SqlitePlatform.js';
+/**
+ * Generic SQLite driver that uses `driverOptions` for the Kysely dialect.
+ * Use this with any SQLite library by passing a Kysely dialect via `driverOptions`.
+ *
+ * For the default better-sqlite3 experience, use `@mikro-orm/sqlite` instead.
+ */
+export class SqliteDriver extends AbstractSqlDriver {
+    constructor(config) {
+        super(config, new SqlitePlatform(), BaseSqliteConnection, ['kysely']);
+    }
+}

package/dialects/sqlite/{BaseSqlitePlatform.d.ts → SqlitePlatform.d.ts}

@@ -3,7 +3,7 @@ import { AbstractSqlPlatform } from '../../AbstractSqlPlatform.js';
 import { SqliteNativeQueryBuilder } from './SqliteNativeQueryBuilder.js';
 import { SqliteSchemaHelper } from './SqliteSchemaHelper.js';
 import { SqliteExceptionConverter } from './SqliteExceptionConverter.js';
-export declare abstract class BaseSqlitePlatform extends AbstractSqlPlatform {
+export declare class SqlitePlatform extends AbstractSqlPlatform {
     protected readonly schemaHelper: SqliteSchemaHelper;
     protected readonly exceptionConverter: SqliteExceptionConverter;
     /** @internal */
@@ -71,6 +71,9 @@ export declare abstract class BaseSqlitePlatform extends AbstractSqlPlatform {
     supportsSchemas(): boolean;
     getDefaultSchemaName(): string | undefined;
     getFullTextWhereClause(): string;
-    quoteVersionValue(value: Date | number, prop: EntityProperty): Date | string | number;
+    escape(value: any): string;
+    convertVersionValue(value: Date | number, prop: EntityProperty): number | {
+        $in: (string | number)[];
+    };
     quoteValue(value: any): string;
 }

package/dialects/sqlite/{BaseSqlitePlatform.js → SqlitePlatform.js}

@@ -2,7 +2,7 @@ import { AbstractSqlPlatform } from '../../AbstractSqlPlatform.js';
 import { SqliteNativeQueryBuilder } from './SqliteNativeQueryBuilder.js';
 import { SqliteSchemaHelper } from './SqliteSchemaHelper.js';
 import { SqliteExceptionConverter } from './SqliteExceptionConverter.js';
-export class BaseSqlitePlatform extends AbstractSqlPlatform {
+export class SqlitePlatform extends AbstractSqlPlatform {
     schemaHelper = new SqliteSchemaHelper(this);
     exceptionConverter = new SqliteExceptionConverter();
     /** @internal */
@@ -19,7 +19,7 @@ export class BaseSqlitePlatform extends AbstractSqlPlatform {
         return true;
     }
     getCurrentTimestampSQL(length) {
-        return super.getCurrentTimestampSQL(0);
+        return `(strftime('%s', 'now') * 1000)`;
     }
     getDateTimeTypeDeclarationSQL(column) {
         return 'datetime';
@@ -101,9 +101,35 @@ export class BaseSqlitePlatform extends AbstractSqlPlatform {
     getFullTextWhereClause() {
         return `:column: match :query`;
     }
-    quoteVersionValue(value, prop) {
+    escape(value) {
+        if (value == null) {
+            return 'null';
+        }
+        if (typeof value === 'boolean') {
+            return value ? 'true' : 'false';
+        }
+        if (typeof value === 'number' || typeof value === 'bigint') {
+            return '' + value;
+        }
+        if (value instanceof Date) {
+            return '' + +value;
+        }
+        if (Array.isArray(value)) {
+            return value.map(v => this.escape(v)).join(', ');
+        }
+        if (Buffer.isBuffer(value)) {
+            return `X'${value.toString('hex')}'`;
+        }
+        return `'${String(value).replace(/'/g, "''")}'`;
+    }
+    convertVersionValue(value, prop) {
         if (prop.runtimeType === 'Date') {
-            return this.escape(value).replace(/^'|\.\d{3}'$/g, '');
+            const ts = +value;
+            const str = new Date(ts)
+                .toISOString()
+                .replace('T', ' ')
+                .replace(/\.\d{3}Z$/, '');
+            return { $in: [ts, str] };
         }
         return value;
     }

package/dialects/sqlite/SqliteSchemaHelper.d.ts

@@ -39,6 +39,11 @@ export declare class SqliteSchemaHelper extends SchemaHelper {
      */
     private extractViewDefinition;
     private getColumns;
+    /**
+     * SQLite strips outer parentheses from expression defaults (`DEFAULT (expr)` → `expr` in pragma).
+     * We need to add them back so they match what we generate in DDL.
+     */
+    private wrapExpressionDefault;
     private getEnumDefinitions;
     getPrimaryKeys(connection: AbstractSqlConnection, indexes: IndexDef[], tableName: string, schemaName?: string): Promise<string[]>;
     private getIndexes;

package/dialects/sqlite/SqliteSchemaHelper.js

@@ -31,8 +31,8 @@ export class SqliteSchemaHelper extends SchemaHelper {
         return '';
     }
     getListTablesSQL() {
-        return `select name as table_name from sqlite_master where type = 'table' and name != 'sqlite_sequence' and name != 'geometry_columns' and name != 'spatial_ref_sys' `
-            + `union all select name as table_name from sqlite_temp_master where type = 'table' order by name`;
+        return (`select name as table_name from sqlite_master where type = 'table' and name != 'sqlite_sequence' and name != 'geometry_columns' and name != 'spatial_ref_sys' ` +
+            `union all select name as table_name from sqlite_temp_master where type = 'table' order by name`);
     }
     async getAllTables(connection, schemas) {
         const databases = await this.getDatabaseList(connection);
@@ -183,9 +183,11 @@ export class SqliteSchemaHelper extends SchemaHelper {
     getDropColumnsSQL(tableName, columns, schemaName) {
         /* v8 ignore next */
         const name = this.quote((schemaName && schemaName !== this.platform.getDefaultSchemaName() ? schemaName + '.' : '') + tableName);
-        return columns.map(column => {
+        return columns
+            .map(column => {
             return `alter table ${name} drop column ${this.quote(column.name)}`;
-        }).join(';\n');
+        })
+            .join(';\n');
     }
     getCreateIndexSQL(tableName, index) {
         /* v8 ignore next */
@@ -286,7 +288,7 @@ export class SqliteSchemaHelper extends SchemaHelper {
             return {
                 name: col.name,
                 type: col.type,
-                default: col.dflt_value,
+                default: this.wrapExpressionDefault(col.dflt_value),
                 nullable: !col.notnull,
                 primary: !!col.pk,
                 mappedType,
@@ -296,6 +298,25 @@ export class SqliteSchemaHelper extends SchemaHelper {
             };
         });
     }
+    /**
+     * SQLite strips outer parentheses from expression defaults (`DEFAULT (expr)` → `expr` in pragma).
+     * We need to add them back so they match what we generate in DDL.
+     */
+    wrapExpressionDefault(value) {
+        if (value == null) {
+            return null;
+        }
+        // simple values that are returned as-is from pragma (no wrapping needed)
+        if (/^-?\d/.test(value) || /^[xX]'/.test(value) || value[0] === "'" || value[0] === '"' || value[0] === '(') {
+            return value;
+        }
+        const lower = value.toLowerCase();
+        if (['null', 'true', 'false', 'current_timestamp', 'current_date', 'current_time'].includes(lower)) {
+            return value;
+        }
+        // everything else is an expression that had its outer parens stripped
+        return `(${value})`;
+    }
     async getEnumDefinitions(connection, tableName, schemaName) {
         const prefix = this.getSchemaPrefix(schemaName);
         const sql = `select sql from ${prefix}sqlite_master where type = ? and name = ?`;
@@ -434,10 +455,10 @@ export class SqliteSchemaHelper extends SchemaHelper {
     alterTable(diff, safe) {
         const ret = [];
         const [schemaName, tableName] = this.splitTableName(diff.name);
-        if (Utils.hasObjectKeys(diff.removedChecks)
-            || Utils.hasObjectKeys(diff.changedChecks)
-            || Utils.hasObjectKeys(diff.changedForeignKeys)
-            || Utils.hasObjectKeys(diff.changedColumns)) {
+        if (Utils.hasObjectKeys(diff.removedChecks) ||
+            Utils.hasObjectKeys(diff.changedChecks) ||
+            Utils.hasObjectKeys(diff.changedForeignKeys) ||
+            Utils.hasObjectKeys(diff.changedColumns)) {
             return this.getAlterTempTableSQL(diff);
         }
         for (const index of Object.values(diff.removedIndexes)) {
@@ -477,7 +498,7 @@ export class SqliteSchemaHelper extends SchemaHelper {
         return ret;
     }
     getAlterTempTableSQL(changedTable) {
-        const tempName = `${(changedTable.toTable.name)}__temp_alter`;
+        const tempName = `${changedTable.toTable.name}__temp_alter`;
         const quotedName = this.quote(changedTable.toTable.name);
         const quotedTempName = this.quote(tempName);
         const [first, ...rest] = this.createTable(changedTable.toTable);

package/dialects/sqlite/index.d.ts

@@ -1,4 +1,6 @@
 export * from './BaseSqliteConnection.js';
-export * from './BaseSqlitePlatform.js';
+export * from './NodeSqliteDialect.js';
+export * from './SqliteDriver.js';
+export * from './SqlitePlatform.js';
 export * from './SqliteSchemaHelper.js';
 export * from './SqliteNativeQueryBuilder.js';

package/dialects/sqlite/index.js

@@ -1,4 +1,6 @@
 export * from './BaseSqliteConnection.js';
-export * from './BaseSqlitePlatform.js';
+export * from './NodeSqliteDialect.js';
+export * from './SqliteDriver.js';
+export * from './SqlitePlatform.js';
 export * from './SqliteSchemaHelper.js';
 export * from './SqliteNativeQueryBuilder.js';

package/package.json

@@ -1,44 +1,44 @@
 {
   "name": "@mikro-orm/sql",
-  "version": "7.0.0-rc.1",
+  "version": "7.0.0-rc.3",
   "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.",
-  "type": "module",
-  "exports": {
-    "./package.json": "./package.json",
-    ".": "./index.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+ssh://git@github.com/mikro-orm/mikro-orm.git"
-  },
   "keywords": [
-    "orm",
+    "data-mapper",
+    "ddd",
+    "entity",
+    "identity-map",
+    "javascript",
+    "js",
+    "mariadb",
+    "mikro-orm",
     "mongo",
     "mongodb",
     "mysql",
-    "mariadb",
+    "orm",
     "postgresql",
     "sqlite",
     "sqlite3",
     "ts",
     "typescript",
-    "js",
-    "javascript",
-    "entity",
-    "ddd",
-    "mikro-orm",
-    "unit-of-work",
-    "data-mapper",
-    "identity-map"
+    "unit-of-work"
   ],
-  "author": "Martin Adámek",
-  "license": "MIT",
+  "homepage": "https://mikro-orm.io",
   "bugs": {
     "url": "https://github.com/mikro-orm/mikro-orm/issues"
   },
-  "homepage": "https://mikro-orm.io",
-  "engines": {
-    "node": ">= 22.17.0"
+  "license": "MIT",
+  "author": "Martin Adámek",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/mikro-orm/mikro-orm.git"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./index.js"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "build": "yarn compile && yarn copy",
@@ -46,16 +46,16 @@
     "compile": "yarn run -T tsc -p tsconfig.build.json",
     "copy": "node ../../scripts/copy.mjs"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "dependencies": {
     "kysely": "0.28.11"
   },
   "devDependencies": {
-    "@mikro-orm/core": "^6.6.4"
+    "@mikro-orm/core": "^6.6.8"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.0.0-rc.1"
+    "@mikro-orm/core": "7.0.0-rc.3"
+  },
+  "engines": {
+    "node": ">= 22.17.0"
   }
 }

package/plugin/transformer.js

@@ -79,12 +79,8 @@ export class MikroTransformer extends OperationNodeTransformer {
                     }
                 }
             }
-            const nodeWithHooks = this.options.processOnCreateHooks && entityMeta
-                ? this.processOnCreateHooks(node, entityMeta)
-                : node;
-            const nodeWithConvertedValues = this.options.convertValues && entityMeta
-                ? this.processInsertValues(nodeWithHooks, entityMeta)
-                : nodeWithHooks;
+            const nodeWithHooks = this.options.processOnCreateHooks && entityMeta ? this.processOnCreateHooks(node, entityMeta) : node;
+            const nodeWithConvertedValues = this.options.convertValues && entityMeta ? this.processInsertValues(nodeWithHooks, entityMeta) : nodeWithHooks;
             // Handle ON CONFLICT clause
             let finalNode = nodeWithConvertedValues;
             if (node.onConflict?.updates && entityMeta) {
@@ -150,12 +146,8 @@ export class MikroTransformer extends OperationNodeTransformer {
                     this.processJoinNode(join, currentContext);
                 }
             }
-            const nodeWithHooks = this.options.processOnUpdateHooks && entityMeta
-                ? this.processOnUpdateHooks(node, entityMeta)
-                : node;
-            const nodeWithConvertedValues = this.options.convertValues && entityMeta
-                ? this.processUpdateValues(nodeWithHooks, entityMeta)
-                : nodeWithHooks;
+            const nodeWithHooks = this.options.processOnUpdateHooks && entityMeta ? this.processOnUpdateHooks(node, entityMeta) : node;
+            const nodeWithConvertedValues = this.options.convertValues && entityMeta ? this.processUpdateValues(nodeWithHooks, entityMeta) : nodeWithHooks;
             return super.transformUpdateQuery(nodeWithConvertedValues, queryId);
         }
         finally {
@@ -217,7 +209,9 @@ export class MikroTransformer extends OperationNodeTransformer {
         }
         // Transform column names when columnNamingStrategy is 'property'
         // Support ColumnNode, ColumnUpdateNode, and ReferenceNode (for JOIN conditions)
-        if (this.options.columnNamingStrategy === 'property' && parent && (ColumnNode.is(parent) || ColumnUpdateNode.is(parent) || ReferenceNode.is(parent))) {
+        if (this.options.columnNamingStrategy === 'property' &&
+            parent &&
+            (ColumnNode.is(parent) || ColumnUpdateNode.is(parent) || ReferenceNode.is(parent))) {
             const ownerMeta = this.findOwnerEntityInContext();
             if (ownerMeta) {
                 const prop = ownerMeta.properties[node.name];
@@ -480,7 +474,11 @@ export class MikroTransformer extends OperationNodeTransformer {
             }
         }
         if (prop.customType && !isRaw(value)) {
-            return prop.customType.convertToDatabaseValue(value, this.platform, { fromQuery: true, key: prop.name, mode: 'query-data' });
+            return prop.customType.convertToDatabaseValue(value, this.platform, {
+                fromQuery: true,
+                key: prop.name,
+                mode: 'query-data',
+            });
         }
         if (value instanceof Date) {
             return this.platform.processDateProperty(value);
@@ -723,7 +721,9 @@ export class MikroTransformer extends OperationNodeTransformer {
      */
     transformResult(rows, entityMap) {
         // Only transform if columnNamingStrategy is 'property' or convertValues is true, and we have data
-        if ((this.options.columnNamingStrategy !== 'property' && !this.options.convertValues) || !rows || rows.length === 0) {
+        if ((this.options.columnNamingStrategy !== 'property' && !this.options.convertValues) ||
+            !rows ||
+            rows.length === 0) {
             return rows;
         }
         // If no entities found (e.g. raw query without known tables), return rows as is
@@ -870,7 +870,8 @@ export class MikroTransformer extends OperationNodeTransformer {
             }
             // For non-local timezone, check if value already has timezone info
             // Number (timestamp) doesn't need timezone handling, string needs check
-            if (typeof value === 'number' || (typeof value === 'string' && (value.includes('+') || value.lastIndexOf('-') > 10 || value.endsWith('Z')))) {
+            if (typeof value === 'number' ||
+                (typeof value === 'string' && (value.includes('+') || value.lastIndexOf('-') > 10 || value.endsWith('Z')))) {
                 return this.platform.parseDate(value);
             }
             // Append timezone if not present (only for string values)

package/query/CriteriaNode.js

@@ -53,22 +53,34 @@ export class CriteriaNode {
         const type = this.prop ? this.prop.kind : null;
         const composite = this.prop?.joinColumns ? this.prop.joinColumns.length > 1 : false;
         const rawField = RawQueryFragment.isKnownFragmentSymbol(this.key);
-        const scalar = payload === null || Utils.isPrimaryKey(payload) || payload instanceof RegExp || payload instanceof Date || rawField;
+        const scalar = payload === null ||
+            Utils.isPrimaryKey(payload) ||
+            payload instanceof RegExp ||
+            payload instanceof Date ||
+            rawField;
         const operator = Utils.isPlainObject(payload) && Utils.getObjectQueryKeys(payload).every(k => Utils.isOperator(k, false));
         if (composite) {
             return true;
         }
         switch (type) {
-            case ReferenceKind.MANY_TO_ONE: return false;
-            case ReferenceKind.ONE_TO_ONE: return !this.prop.owner;
-            case ReferenceKind.ONE_TO_MANY: return scalar || operator;
-            case ReferenceKind.MANY_TO_MANY: return scalar || operator;
-            default: return false;
+            case ReferenceKind.MANY_TO_ONE:
+                return false;
+            case ReferenceKind.ONE_TO_ONE:
+                return !this.prop.owner;
+            case ReferenceKind.ONE_TO_MANY:
+                return scalar || operator;
+            case ReferenceKind.MANY_TO_MANY:
+                return scalar || operator;
+            default:
+                return false;
         }
     }
     renameFieldToPK(qb, ownerAlias) {
         const joinAlias = qb.getAliasForJoinPath(this.getPath(), { matchPopulateJoins: true });
-        if (!joinAlias && this.parent && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind) && this.prop.owner) {
+        if (!joinAlias &&
+            this.parent &&
+            [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind) &&
+            this.prop.owner) {
             const alias = qb.getAliasForJoinPath(this.parent.getPath()) ?? ownerAlias ?? qb.alias;
             return Utils.getPrimaryKeyHash(this.prop.joinColumns.map(col => `${alias}.${col}`));
         }
@@ -84,7 +96,9 @@ export class CriteriaNode {
         const parentPath = opts?.parentPath ?? this.parent?.getPath({ addIndex: addParentIndex }) ?? Utils.className(this.entityName);
         const index = opts?.addIndex && this.index != null ? `[${this.index}]` : '';
         // ignore group operators to allow easier mapping (e.g. for orderBy)
-        const key = this.key && !RawQueryFragment.isKnownFragmentSymbol(this.key) && !['$and', '$or', '$not'].includes(this.key) ? '.' + this.key : '';
+        const key = this.key && !RawQueryFragment.isKnownFragmentSymbol(this.key) && !['$and', '$or', '$not'].includes(this.key)
+            ? '.' + this.key
+            : '';
         const ret = parentPath + index + key;
         if (this.isPivotJoin()) {
             // distinguish pivot table join from target entity join
@@ -97,7 +111,11 @@ export class CriteriaNode {
             return false;
         }
         const rawField = RawQueryFragment.isKnownFragmentSymbol(this.key);
-        const scalar = this.payload === null || Utils.isPrimaryKey(this.payload) || this.payload instanceof RegExp || this.payload instanceof Date || rawField;
+        const scalar = this.payload === null ||
+            Utils.isPrimaryKey(this.payload) ||
+            this.payload instanceof RegExp ||
+            this.payload instanceof Date ||
+            rawField;
         const operator = Utils.isObject(this.payload) && Utils.getObjectQueryKeys(this.payload).every(k => Utils.isOperator(k, false));
         return this.prop.kind === ReferenceKind.MANY_TO_MANY && (scalar || operator);
     }
@@ -116,7 +134,7 @@ export class CriteriaNode {
         const o = {};
         ['entityName', 'key', 'index', 'payload']
             .filter(k => this[k] !== undefined)
-            .forEach(k => o[k] = this[k]);
+            .forEach(k => (o[k] = this[k]));
         return `${this.constructor.name} ${inspect(o)}`;
     }
 }

package/query/CriteriaNodeFactory.js

@@ -8,7 +8,11 @@ import { ScalarCriteriaNode } from './ScalarCriteriaNode.js';
 export class CriteriaNodeFactory {
     static createNode(metadata, entityName, payload, parent, key, validate = true) {
         const rawField = RawQueryFragment.isKnownFragmentSymbol(key);
-        const scalar = Utils.isPrimaryKey(payload) || isRaw(payload) || payload instanceof RegExp || payload instanceof Date || rawField;
+        const scalar = Utils.isPrimaryKey(payload) ||
+            isRaw(payload) ||
+            payload instanceof RegExp ||
+            payload instanceof Date ||
+            rawField;
         if (Array.isArray(payload) && !scalar) {
             return this.createArrayNode(metadata, entityName, payload, parent, key, validate);
         }

package/query/NativeQueryBuilder.d.ts

@@ -1,6 +1,17 @@
 import { type Dictionary, LockMode, type QueryFlag, RawQueryFragment, type Subquery } from '@mikro-orm/core';
 import { QueryType } from './enums.js';
 import type { AbstractSqlPlatform } from '../AbstractSqlPlatform.js';
+export interface CteOptions {
+    columns?: string[];
+    /** PostgreSQL: MATERIALIZED / NOT MATERIALIZED */
+    materialized?: boolean;
+}
+interface CteClause extends CteOptions {
+    name: string;
+    sql: string;
+    params: unknown[];
+    recursive?: boolean;
+}
 interface Options {
     tableName?: string | RawQueryFragment;
     indexHint?: string;
@@ -32,6 +43,7 @@ interface Options {
     hintComment?: string[];
     flags?: Set<QueryFlag>;
     wrap?: [prefix: string, suffix: string];
+    ctes?: CteClause[];
 }
 interface TableOptions {
     schema?: string;
@@ -65,6 +77,17 @@ export declare class NativeQueryBuilder implements Subquery {
     groupBy(groupBy: (string | RawQueryFragment)[]): this;
     join(sql: string, params: unknown[]): this;
     orderBy(orderBy: string): this;
+    /**
+     * The sub-query is compiled eagerly at call time — later mutations to the
+     * sub-query builder will not be reflected in this CTE.
+     */
+    with(name: string, query: NativeQueryBuilder | RawQueryFragment, options?: CteOptions): this;
+    /**
+     * Adds a recursive CTE (`WITH RECURSIVE` on PostgreSQL/MySQL/SQLite, plain `WITH` on MSSQL).
+     * The sub-query is compiled eagerly — later mutations will not be reflected.
+     */
+    withRecursive(name: string, query: NativeQueryBuilder | RawQueryFragment, options?: CteOptions): this;
+    private addCte;
     toString(): string;
     compile(): {
         sql: string;
@@ -103,6 +126,8 @@ export declare class NativeQueryBuilder implements Subquery {
     protected compileDelete(): void;
     protected compileTruncate(): void;
     protected addHintComment(): void;
+    protected compileCtes(): void;
+    protected getCteKeyword(hasRecursive: boolean): string;
     protected getTableName(): string;
     protected quote(id: string | RawQueryFragment | NativeQueryBuilder): string;
 }

package/query/NativeQueryBuilder.js

@@ -1,4 +1,4 @@
-import { LockMode, raw, RawQueryFragment, Utils } from '@mikro-orm/core';
+import { LockMode, raw, RawQueryFragment, Utils, } from '@mikro-orm/core';
 import { QueryType } from './enums.js';
 /** @internal */
 export class NativeQueryBuilder {
@@ -59,6 +59,36 @@ export class NativeQueryBuilder {
         this.options.orderBy = orderBy;
         return this;
     }
+    /**
+     * The sub-query is compiled eagerly at call time — later mutations to the
+     * sub-query builder will not be reflected in this CTE.
+     */
+    with(name, query, options) {
+        return this.addCte(name, query, options);
+    }
+    /**
+     * Adds a recursive CTE (`WITH RECURSIVE` on PostgreSQL/MySQL/SQLite, plain `WITH` on MSSQL).
+     * The sub-query is compiled eagerly — later mutations will not be reflected.
+     */
+    withRecursive(name, query, options) {
+        return this.addCte(name, query, options, true);
+    }
+    addCte(name, query, options, recursive) {
+        this.options.ctes ??= [];
+        if (this.options.ctes.some(cte => cte.name === name)) {
+            throw new Error(`CTE with name '${name}' already exists`);
+        }
+        const { sql, params } = query instanceof NativeQueryBuilder ? query.compile() : { sql: query.sql, params: [...query.params] };
+        this.options.ctes.push({
+            name,
+            sql,
+            params,
+            recursive,
+            columns: options?.columns,
+            materialized: options?.materialized,
+        });
+        return this;
+    }
     toString() {
         const { sql, params } = this.compile();
         return this.platform.formatQuery(sql, params);
@@ -72,6 +102,7 @@ export class NativeQueryBuilder {
         if (this.options.comment) {
             this.parts.push(...this.options.comment.map(comment => `/* ${comment} */`));
         }
+        this.compileCtes();
         switch (this.type) {
             case QueryType.SELECT:
             case QueryType.COUNT:
@@ -387,6 +418,35 @@ export class NativeQueryBuilder {
             this.parts.push(`/*+ ${this.options.hintComment.join(' ')} */`);
         }
     }
+    compileCtes() {
+        const ctes = this.options.ctes;
+        if (!ctes || ctes.length === 0) {
+            return;
+        }
+        const hasRecursive = ctes.some(cte => cte.recursive);
+        const keyword = this.getCteKeyword(hasRecursive);
+        const cteParts = [];
+        for (const cte of ctes) {
+            let part = this.quote(cte.name);
+            if (cte.columns?.length) {
+                part += ` (${cte.columns.map(c => this.quote(c)).join(', ')})`;
+            }
+            part += ' as';
+            if (cte.materialized === true) {
+                part += ' materialized';
+            }
+            else if (cte.materialized === false) {
+                part += ' not materialized';
+            }
+            part += ` (${cte.sql})`;
+            this.params.push(...cte.params);
+            cteParts.push(part);
+        }
+        this.parts.push(`${keyword} ${cteParts.join(', ')}`);
+    }
+    getCteKeyword(hasRecursive) {
+        return hasRecursive ? 'with recursive' : 'with';
+    }
     getTableName() {
         if (!this.options.tableName) {
             throw new Error('No table name provided');