feat: support for Common Table Expressions

Resolves #1116 #5899

docs/select-query-builder.md

@@ -1148,3 +1148,36 @@ const users = await connection.getRepository(User)
 
 You will get all the rows, including the ones which are deleted.
 
+## Common table expressions
+
+`QueryBuilder` instances
+support [common table expressions](https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression)
+, if minimal supported version of your database supports them.
+
+```typescript
+const users = await connection.getRepository(User)
+    .createQueryBuilder('user')
+    .select("user.id", 'id')
+    .addCommonTableExpression(`
+      SELECT "userId" FROM "post"
+    `, 'post_users_ids')
+    .where(`user.id IN (SELECT "userId" FROM 'post_users_ids')`)
+    .getMany();
+```
+
+Result values of `InsertQueryBuilder` or `UpdateQueryBuilder` can be used in Postgres:
+
+```typescript
+const insertQueryBuilder = await connection.getRepository(User)
+    .createQueryBuilder()
+    .insert({
+        name: 'John Smith'
+    })
+    .returning(['id']);
+
+const users = await connection.getRepository(User)
+    .createQueryBuilder('user')
+    .addCommonTableExpression(insertQueryBuilder, 'insert_results')
+    .where(`user.id IN (SELECT "id" FROM 'insert_results')`)
+    .getMany();
+```

src/driver/Driver.ts

@@ -2,6 +2,7 @@ import {QueryRunner} from "../query-runner/QueryRunner";
 import {ColumnMetadata} from "../metadata/ColumnMetadata";
 import {ObjectLiteral} from "../common/ObjectLiteral";
 import {ColumnType} from "./types/ColumnTypes";
+import {CteCapabilities} from "./types/CteCapabilities";
 import {MappedColumnTypes} from "./types/MappedColumnTypes";
 import {SchemaBuilder} from "../schema-builder/SchemaBuilder";
 import {DataTypeDefaults} from "./types/DataTypeDefaults";
@@ -93,6 +94,8 @@ export interface Driver {
      */
     maxAliasLength?: number;
 
+    cteCapabilities: CteCapabilities;
+
     /**
      * Performs connection to the database.
      * Depend on driver type it may create a connection pool.

src/driver/aurora-data-api/AuroraDataApiDriver.ts

@@ -1,5 +1,6 @@
 import {Driver} from "../Driver";
 import {DriverUtils} from "../DriverUtils";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {AuroraDataApiQueryRunner} from "./AuroraDataApiQueryRunner";
 import {ObjectLiteral} from "../../common/ObjectLiteral";
 import {ColumnMetadata} from "../../metadata/ColumnMetadata";
@@ -298,13 +299,14 @@ export class AuroraDataApiDriver implements Driver {
         "bigint": { width: 20 }
     };
 
-
     /**
      * Max length allowed by MySQL for aliases.
      * @see https://dev.mysql.com/doc/refman/5.5/en/identifiers.html
      */
     maxAliasLength = 63;
 
+    cteCapabilities: CteCapabilities = {};
+
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------

src/driver/cockroachdb/CockroachDriver.ts

@@ -4,6 +4,7 @@ import {ObjectLiteral} from "../../common/ObjectLiteral";
 import {DriverPackageNotInstalledError} from "../../error/DriverPackageNotInstalledError";
 import {DriverUtils} from "../DriverUtils";
 import {ColumnMetadata} from "../../metadata/ColumnMetadata";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {CockroachConnectionCredentialsOptions} from "./CockroachConnectionCredentialsOptions";
 import {CockroachConnectionOptions} from "./CockroachConnectionOptions";
 import {DateUtils} from "../../util/DateUtils";
@@ -232,6 +233,8 @@ export class CockroachDriver implements Driver {
      */
     maxAliasLength?: number;
 
+    cteCapabilities: CteCapabilities = { writable: true, materializedHint: true, requiresRecursiveHint: true };
+
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------

src/driver/mongodb/MongoDriver.ts

@@ -1,6 +1,7 @@
 import {Driver} from "../Driver";
 import {ConnectionIsNotSetError} from "../../error/ConnectionIsNotSetError";
 import {DriverPackageNotInstalledError} from "../../error/DriverPackageNotInstalledError";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {MongoQueryRunner} from "./MongoQueryRunner";
 import {ObjectLiteral} from "../../common/ObjectLiteral";
 import {ColumnMetadata} from "../../metadata/ColumnMetadata";
@@ -207,6 +208,8 @@ export class MongoDriver implements Driver {
         "retryWrites"
     ];
 
+    cteCapabilities: CteCapabilities = {};
+
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------

src/driver/mysql/MysqlDriver.ts

@@ -2,6 +2,7 @@ import {Driver} from "../Driver";
 import {ConnectionIsNotSetError} from "../../error/ConnectionIsNotSetError";
 import {DriverPackageNotInstalledError} from "../../error/DriverPackageNotInstalledError";
 import {DriverUtils} from "../DriverUtils";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {MysqlQueryRunner} from "./MysqlQueryRunner";
 import {ObjectLiteral} from "../../common/ObjectLiteral";
 import {ColumnMetadata} from "../../metadata/ColumnMetadata";
@@ -304,6 +305,10 @@ export class MysqlDriver implements Driver {
      */
     maxAliasLength = 63;
 
+    cteCapabilities: CteCapabilities = {
+        requiresRecursiveHint: true,
+    };
+
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------

src/driver/oracle/OracleDriver.ts

@@ -1,6 +1,7 @@
 import {Driver} from "../Driver";
 import {ConnectionIsNotSetError} from "../../error/ConnectionIsNotSetError";
 import {DriverPackageNotInstalledError} from "../../error/DriverPackageNotInstalledError";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {OracleQueryRunner} from "./OracleQueryRunner";
 import {ObjectLiteral} from "../../common/ObjectLiteral";
 import {ColumnMetadata} from "../../metadata/ColumnMetadata";
@@ -217,6 +218,8 @@ export class OracleDriver implements Driver {
      */
     maxAliasLength = 30;
 
+    cteCapabilities: CteCapabilities = {};
+
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------

src/driver/postgres/PostgresDriver.ts

@@ -13,6 +13,7 @@ import {DateUtils} from "../../util/DateUtils";
 import {OrmUtils} from "../../util/OrmUtils";
 import {Driver} from "../Driver";
 import {ColumnType} from "../types/ColumnTypes";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {DataTypeDefaults} from "../types/DataTypeDefaults";
 import {MappedColumnTypes} from "../types/MappedColumnTypes";
 import {ReplicationMode} from "../types/ReplicationMode";
@@ -271,6 +272,12 @@ export class PostgresDriver implements Driver {
      */
     maxAliasLength = 63;
 
+    cteCapabilities: CteCapabilities = {
+        writable: true,
+        requiresRecursiveHint: true,
+        materializedHint: true,
+    };
+
     isGeneratedColumnsSupported: boolean = false;
 
     // -------------------------------------------------------------------------

src/driver/sap/SapDriver.ts

@@ -16,6 +16,7 @@ import {ApplyValueTransformers} from "../../util/ApplyValueTransformers";
 import {DateUtils} from "../../util/DateUtils";
 import {OrmUtils} from "../../util/OrmUtils";
 import {Driver} from "../Driver";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {DataTypeDefaults} from "../types/DataTypeDefaults";
 import {MappedColumnTypes} from "../types/MappedColumnTypes";
 import {SapConnectionOptions} from "./SapConnectionOptions";
@@ -206,6 +207,8 @@ export class SapDriver implements Driver {
      */
     maxAliasLength = 128;
 
+    cteCapabilities: CteCapabilities = {};
+
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------

src/driver/sqlite-abstract/AbstractSqliteDriver.ts

@@ -4,6 +4,7 @@ import {ColumnMetadata} from "../../metadata/ColumnMetadata";
 import {DateUtils} from "../../util/DateUtils";
 import {Connection} from "../../connection/Connection";
 import {RdbmsSchemaBuilder} from "../../schema-builder/RdbmsSchemaBuilder";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {MappedColumnTypes} from "../types/MappedColumnTypes";
 import {ColumnType} from "../types/ColumnTypes";
 import {QueryRunner} from "../../query-runner/QueryRunner";
@@ -216,6 +217,10 @@ export abstract class AbstractSqliteDriver implements Driver {
      */
     maxAliasLength?: number;
 
+    cteCapabilities: CteCapabilities = {
+        requiresRecursiveHint: true,
+    };
+
     // -------------------------------------------------------------------------
     // Protected Properties
     // -------------------------------------------------------------------------

src/driver/sqlserver/SqlServerDriver.ts

@@ -2,6 +2,7 @@ import {Driver} from "../Driver";
 import {ConnectionIsNotSetError} from "../../error/ConnectionIsNotSetError";
 import {DriverPackageNotInstalledError} from "../../error/DriverPackageNotInstalledError";
 import {DriverUtils} from "../DriverUtils";
+import { CteCapabilities } from "../types/CteCapabilities";
 import {SqlServerQueryRunner} from "./SqlServerQueryRunner";
 import {ObjectLiteral} from "../../common/ObjectLiteral";
 import {ColumnMetadata} from "../../metadata/ColumnMetadata";
@@ -223,6 +224,11 @@ export class SqlServerDriver implements Driver {
         "datetimeoffset": { precision: 7 }
     };
 
+    cteCapabilities: CteCapabilities = {
+        // todo: enable it for SQL Server - it's partially supported, but there are issues with generation of non-standard OUTPUT clause
+        writable: false,
+    };
+
     /**
      * Max length allowed by MSSQL Server for aliases (identifiers).
      * @see https://docs.microsoft.com/en-us/sql/sql-server/maximum-capacity-specifications-for-sql-server

src/driver/types/CteCapabilities.ts

@@ -0,0 +1,15 @@
+export interface CteCapabilities {
+    /**
+     * Are RETURNING clauses supported in CTEs?
+     */
+    writable?: boolean;
+    /**
+     * Is RECURSIVE clause required for recursive CTEs?
+     */
+    requiresRecursiveHint?: boolean;
+
+    /**
+     * Is MATERIALIZED clause supported?
+     */
+    materializedHint?: boolean;
+}

src/query-builder/DeleteQueryBuilder.ts

@@ -35,6 +35,7 @@ export class DeleteQueryBuilder<Entity> extends QueryBuilder<Entity> implements
      */
     getQuery(): string {
         let sql = this.createComment();
+        sql += this.createCteExpression();
         sql += this.createDeleteExpression();
         return sql.trim();
     }

src/query-builder/InsertQueryBuilder.ts

@@ -34,6 +34,7 @@ export class InsertQueryBuilder<Entity> extends QueryBuilder<Entity> {
      */
     getQuery(): string {
         let sql = this.createComment();
+        sql += this.createCteExpression();
         sql += this.createInsertExpression();
         return sql.trim();
     }