kysely 0.27.2 → 0.27.4

package/dist/esm/query-builder/update-query-builder.js

@@ -10,6 +10,9 @@ import { freeze } from '../util/object-utils.js';
 import { UpdateResult } from './update-result.js';
 import { isNoResultErrorConstructor, NoResultError, } from './no-result-error.js';
 import { parseReferentialBinaryOperation, parseValueBinaryOperationOrExpression, } from '../parser/binary-operation-parser.js';
+import { parseValueExpression, } from '../parser/value-parser.js';
+import { LimitNode } from '../operation-node/limit-node.js';
+import { parseTop } from '../parser/top-parser.js';
 export class UpdateQueryBuilder {
     #props;
     constructor(props) {
@@ -33,6 +36,51 @@ export class UpdateQueryBuilder {
             queryNode: QueryNode.cloneWithoutWhere(this.#props.queryNode),
         });
     }
+    /**
+     * Changes an `update` query into a `update top` query.
+     *
+     * `top` clause is only supported by some dialects like MS SQL Server.
+     *
+     * ### Examples
+     *
+     * Update the first row:
+     *
+     * ```ts
+     * await db.updateTable('person')
+     *   .top(1)
+     *   .set({ first_name: 'Foo' })
+     *   .where('age', '>', 18)
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MS SQL Server):
+     *
+     * ```sql
+     * update top(1) "person" set "first_name" = @1 where "age" > @2
+     * ```
+     *
+     * Update the 50% first rows:
+     *
+     * ```ts
+     * await db.updateTable('person')
+     *   .top(50, 'percent')
+     *   .set({ first_name: 'Foo' })
+     *   .where('age', '>', 18)
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MS SQL Server):
+     *
+     * ```sql
+     * update top(50) percent "person" set "first_name" = @1 where "age" > @2
+     * ```
+     */
+    top(expression, modifiers) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithTop(this.#props.queryNode, parseTop(expression, modifiers)),
+        });
+    }
     from(from) {
         return new UpdateQueryBuilder({
             ...this.#props,
@@ -63,6 +111,31 @@ export class UpdateQueryBuilder {
             queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('FullJoin', args)),
         });
     }
+    /**
+     * Adds a limit clause to the update query for supported databases, such as MySQL.
+     *
+     * ### Examples
+     *
+     * Update the first 2 rows in the 'person' table:
+     *
+     * ```ts
+     * return await db
+     *   .updateTable('person')
+     *   .set({ first_name: 'Foo' })
+     *   .limit(2);
+     * ```
+     *
+     * The generated SQL (MySQL):
+     * ```sql
+     * update `person` set `first_name` = 'Foo' limit 2
+     * ```
+     */
+    limit(limit) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: UpdateQueryNode.cloneWithLimit(this.#props.queryNode, LimitNode.create(parseValueExpression(limit))),
+        });
+    }
     set(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
@@ -75,10 +148,47 @@ export class UpdateQueryBuilder {
             queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectArg(selection)),
         });
     }
-    returningAll() {
+    returningAll(table) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll(table)),
+        });
+    }
+    output(args) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOutput(this.#props.queryNode, parseSelectArg(args)),
+        });
+    }
+    outputAll(table) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOutput(this.#props.queryNode, parseSelectAll(table)),
+        });
+    }
+    /**
+     * Clears all `returning` clauses from the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.updateTable('person')
+     *   .returningAll()
+     *   .set({ age: 39 })
+     *   .where('first_name', '=', 'John')
+     *   .clearReturning()
+     * ```
+     *
+     * The generated SQL(PostgreSQL):
+     *
+     * ```sql
+     * update "person" set "age" = 39 where "first_name" = "John"
+     * ```
+     */
+    clearReturning() {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll()),
+            queryNode: QueryNode.cloneWithoutReturning(this.#props.queryNode),
         });
     }
     /**
@@ -210,17 +320,17 @@ export class UpdateQueryBuilder {
     /**
      * Asserts that query's output row type equals the given type `T`.
      *
-     * This method can be used to simplify excessively complex types to make typescript happy
+     * This method can be used to simplify excessively complex types to make TypeScript happy
      * and much faster.
      *
      * Kysely uses complex type magic to achieve its type safety. This complexity is sometimes too much
-     * for typescript and you get errors like this:
+     * for TypeScript and you get errors like this:
      *
      * ```
      * error TS2589: Type instantiation is excessively deep and possibly infinite.
      * ```
      *
-     * In these case you can often use this method to help typescript a little bit. When you use this
+     * In these case you can often use this method to help TypeScript a little bit. When you use this
      * method to assert the output type of a query, Kysely can drop the complex output type that
      * consists of multiple nested helper types and replace it with the simple asserted type.
      *
@@ -275,9 +385,11 @@ export class UpdateQueryBuilder {
      */
     async execute() {
         const compiledQuery = this.compile();
-        const query = compiledQuery.query;
         const result = await this.#props.executor.executeQuery(compiledQuery, this.#props.queryId);
-        if (this.#props.executor.adapter.supportsReturning && query.returning) {
+        const { adapter } = this.#props.executor;
+        const query = compiledQuery.query;
+        if ((query.returning && adapter.supportsReturning) ||
+            (query.output && adapter.supportsOutput)) {
             return result.rows;
         }
         return [

package/dist/esm/query-builder/update-result.d.ts

@@ -1,5 +1,14 @@
 export declare class UpdateResult {
+    /**
+     * The number of rows the update query updated (even if not changed).
+    */
     readonly numUpdatedRows: bigint;
+    /**
+     * The number of rows the update query changed.
+     *
+     * This is **optional** and only supported in dialects such as MySQL.
+     * You would probably use {@link numUpdatedRows} in most cases.
+    */
     readonly numChangedRows?: bigint;
     constructor(numUpdatedRows: bigint, numChangedRows: bigint | undefined);
 }

package/dist/esm/query-builder/update-result.js

@@ -1,6 +1,15 @@
 /// <reference types="./update-result.d.ts" />
 export class UpdateResult {
+    /**
+     * The number of rows the update query updated (even if not changed).
+    */
     numUpdatedRows;
+    /**
+     * The number of rows the update query changed.
+     *
+     * This is **optional** and only supported in dialects such as MySQL.
+     * You would probably use {@link numUpdatedRows} in most cases.
+    */
     numChangedRows;
     constructor(numUpdatedRows, numChangedRows) {
         this.numUpdatedRows = numUpdatedRows;

package/dist/esm/query-builder/where-interface.d.ts

@@ -265,7 +265,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     sql`coalesce(first_name, last_name)`,
+     *     sql<string>`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )

package/dist/esm/query-compiler/default-query-compiler.d.ts

@@ -88,7 +88,13 @@ import { JSONPathNode } from '../operation-node/json-path-node.js';
 import { JSONPathLegNode } from '../operation-node/json-path-leg-node.js';
 import { JSONOperatorChainNode } from '../operation-node/json-operator-chain-node.js';
 import { TupleNode } from '../operation-node/tuple-node.js';
+import { MergeQueryNode } from '../operation-node/merge-query-node.js';
+import { MatchedNode } from '../operation-node/matched-node.js';
 import { AddIndexNode } from '../operation-node/add-index-node.js';
+import { CastNode } from '../operation-node/cast-node.js';
+import { FetchNode } from '../operation-node/fetch-node.js';
+import { TopNode } from '../operation-node/top-node.js';
+import { OutputNode } from '../operation-node/output-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -185,7 +191,13 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitJSONPath(node: JSONPathNode): void;
     protected visitJSONPathLeg(node: JSONPathLegNode): void;
     protected visitJSONOperatorChain(node: JSONOperatorChainNode): void;
+    protected visitMergeQuery(node: MergeQueryNode): void;
+    protected visitMatched(node: MatchedNode): void;
     protected visitAddIndex(node: AddIndexNode): void;
+    protected visitCast(node: CastNode): void;
+    protected visitFetch(node: FetchNode): void;
+    protected visitOutput(node: OutputNode): void;
+    protected visitTop(node: TopNode): void;
     protected append(str: string): void;
     protected appendValue(parameter: unknown): void;
     protected getLeftIdentifierWrapper(): string;

package/dist/esm/query-compiler/default-query-compiler.js

@@ -8,6 +8,7 @@ import { QueryNode } from '../operation-node/query-node.js';
 import { freeze, isString, isNumber, isBoolean, isNull, isDate, isBigInt, } from '../util/object-utils.js';
 import { CreateViewNode } from '../operation-node/create-view-node.js';
 import { SetOperationNode } from '../operation-node/set-operation-node.js';
+import { MergeQueryNode } from '../operation-node/merge-query-node.js';
 export class DefaultQueryCompiler extends OperationNodeVisitor {
     #sql = '';
     #parameters = [];
@@ -17,6 +18,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     compileQuery(node) {
         this.#sql = '';
         this.#parameters = [];
+        this.nodeStack.splice(0, this.nodeStack.length);
         this.visitNode(node);
         return freeze({
             query: node,
@@ -54,6 +56,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.compileList(node.frontModifiers, ' ');
         }
+        if (node.top) {
+            this.append(' ');
+            this.visitNode(node.top);
+        }
         if (node.selections) {
             this.append(' ');
             this.compileList(node.selections);
@@ -94,6 +100,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.offset);
         }
+        if (node.fetch) {
+            this.append(' ');
+            this.visitNode(node.fetch);
+        }
         if (node.endModifiers?.length) {
             this.append(' ');
             this.compileList(this.sortSelectModifiers([...node.endModifiers]), ' ');
@@ -135,12 +145,13 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.visitNode(node.having);
     }
     visitInsertQuery(node) {
-        const isSubQuery = this.nodeStack.find(QueryNode.is) !== node;
+        const rootQueryNode = this.nodeStack.find(QueryNode.is);
+        const isSubQuery = rootQueryNode !== node;
         if (!isSubQuery && node.explain) {
             this.visitNode(node.explain);
             this.append(' ');
         }
-        if (isSubQuery) {
+        if (isSubQuery && !MergeQueryNode.is(rootQueryNode)) {
             this.append('(');
         }
         if (node.with) {
@@ -151,13 +162,23 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         if (node.ignore) {
             this.append(' ignore');
         }
-        this.append(' into ');
-        this.visitNode(node.into);
+        if (node.top) {
+            this.append(' ');
+            this.visitNode(node.top);
+        }
+        if (node.into) {
+            this.append(' into ');
+            this.visitNode(node.into);
+        }
         if (node.columns) {
             this.append(' (');
             this.compileList(node.columns);
             this.append(')');
         }
+        if (node.output) {
+            this.append(' ');
+            this.visitNode(node.output);
+        }
         if (node.values) {
             this.append(' ');
             this.visitNode(node.values);
@@ -178,7 +199,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.returning);
         }
-        if (isSubQuery) {
+        if (isSubQuery && !MergeQueryNode.is(rootQueryNode)) {
             this.append(')');
         }
     }
@@ -200,7 +221,15 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
         }
         this.append('delete ');
+        if (node.top) {
+            this.visitNode(node.top);
+            this.append(' ');
+        }
         this.visitNode(node.from);
+        if (node.output) {
+            this.append(' ');
+            this.visitNode(node.output);
+        }
         if (node.using) {
             this.append(' ');
             this.visitNode(node.using);
@@ -371,6 +400,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         }
     }
     visitColumnDefinition(node) {
+        if (node.ifNotExists) {
+            this.append('if not exists ');
+        }
         this.visitNode(node.column);
         this.append(' ');
         this.visitNode(node.dataType);
@@ -385,6 +417,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.generated);
         }
+        if (node.identity) {
+            this.append(' identity');
+        }
         if (node.defaultTo) {
             this.append(' ');
             this.visitNode(node.defaultTo);
@@ -468,12 +503,13 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.visitNode(node.groupBy);
     }
     visitUpdateQuery(node) {
-        const isSubQuery = this.nodeStack.find(QueryNode.is) !== node;
+        const rootQueryNode = this.nodeStack.find(QueryNode.is);
+        const isSubQuery = rootQueryNode !== node;
         if (!isSubQuery && node.explain) {
             this.visitNode(node.explain);
             this.append(' ');
         }
-        if (isSubQuery) {
+        if (isSubQuery && !MergeQueryNode.is(rootQueryNode)) {
             this.append('(');
         }
         if (node.with) {
@@ -481,11 +517,22 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
         }
         this.append('update ');
-        this.visitNode(node.table);
-        this.append(' set ');
+        if (node.top) {
+            this.visitNode(node.top);
+            this.append(' ');
+        }
+        if (node.table) {
+            this.visitNode(node.table);
+            this.append(' ');
+        }
+        this.append('set ');
         if (node.updates) {
             this.compileList(node.updates);
         }
+        if (node.output) {
+            this.append(' ');
+            this.visitNode(node.output);
+        }
         if (node.from) {
             this.append(' ');
             this.visitNode(node.from);
@@ -498,11 +545,15 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.where);
         }
+        if (node.limit) {
+            this.append(' ');
+            this.visitNode(node.limit);
+        }
         if (node.returning) {
             this.append(' ');
             this.visitNode(node.returning);
         }
-        if (isSubQuery) {
+        if (isSubQuery && !MergeQueryNode.is(rootQueryNode)) {
             this.append(')');
         }
     }
@@ -1038,6 +1089,40 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.visitNode(node.values[i]);
         }
     }
+    visitMergeQuery(node) {
+        if (node.with) {
+            this.visitNode(node.with);
+            this.append(' ');
+        }
+        this.append('merge ');
+        if (node.top) {
+            this.visitNode(node.top);
+            this.append(' ');
+        }
+        this.append('into ');
+        this.visitNode(node.into);
+        if (node.using) {
+            this.append(' ');
+            this.visitNode(node.using);
+        }
+        if (node.whens) {
+            this.append(' ');
+            this.compileList(node.whens, ' ');
+        }
+        if (node.output) {
+            this.append(' ');
+            this.visitNode(node.output);
+        }
+    }
+    visitMatched(node) {
+        if (node.not) {
+            this.append('not ');
+        }
+        this.append('matched');
+        if (node.bySource) {
+            this.append(' by source');
+        }
+    }
     visitAddIndex(node) {
         this.append('add ');
         if (node.unique) {
@@ -1055,6 +1140,28 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.visitNode(node.using);
         }
     }
+    visitCast(node) {
+        this.append('cast(');
+        this.visitNode(node.expression);
+        this.append(' as ');
+        this.visitNode(node.dataType);
+        this.append(')');
+    }
+    visitFetch(node) {
+        this.append('fetch next ');
+        this.visitNode(node.rowCount);
+        this.append(` rows ${node.modifier}`);
+    }
+    visitOutput(node) {
+        this.append('output ');
+        this.compileList(node.selections);
+    }
+    visitTop(node) {
+        this.append(`top(${node.expression})`);
+        if (node.modifiers) {
+            this.append(` ${node.modifiers}`);
+        }
+    }
     append(str) {
         this.#sql += str;
     }
@@ -1164,4 +1271,5 @@ const JOIN_TYPE_SQL = freeze({
     FullJoin: 'full join',
     LateralInnerJoin: 'inner join lateral',
     LateralLeftJoin: 'left join lateral',
+    Using: 'using',
 });

package/dist/esm/query-compiler/query-compiler.d.ts

@@ -9,10 +9,11 @@ import { DropSchemaNode } from '../operation-node/drop-schema-node.js';
 import { DropTableNode } from '../operation-node/drop-table-node.js';
 import { DropTypeNode } from '../operation-node/drop-type-node.js';
 import { DropViewNode } from '../operation-node/drop-view-node.js';
+import { MergeQueryNode } from '../operation-node/merge-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { RawNode } from '../operation-node/raw-node.js';
 import { CompiledQuery } from './compiled-query.js';
-export type RootOperationNode = QueryNode | CreateTableNode | CreateIndexNode | CreateSchemaNode | CreateViewNode | DropTableNode | DropIndexNode | DropSchemaNode | DropViewNode | AlterTableNode | RawNode | CreateTypeNode | DropTypeNode;
+export type RootOperationNode = QueryNode | CreateTableNode | CreateIndexNode | CreateSchemaNode | CreateViewNode | DropTableNode | DropIndexNode | DropSchemaNode | DropViewNode | AlterTableNode | RawNode | CreateTypeNode | DropTypeNode | MergeQueryNode;
 /**
  * a `QueryCompiler` compiles a query expressed as a tree of `OperationNodes` into SQL.
  */

package/dist/esm/query-creator.d.ts

@@ -12,6 +12,8 @@ import { UpdateResult } from './query-builder/update-result.js';
 import { KyselyPlugin } from './plugin/kysely-plugin.js';
 import { CTEBuilderCallback } from './query-builder/cte-builder.js';
 import { CallbackSelection, SelectCallback, SelectExpression, Selection } from './parser/select-parser.js';
+import { MergeQueryBuilder } from './query-builder/merge-query-builder.js';
+import { MergeResult } from './query-builder/merge-result.js';
 export declare class QueryCreator<DB> {
     #private;
     constructor(props: QueryCreatorProps);
@@ -123,10 +125,10 @@ export declare class QueryCreator<DB> {
      * ```
      */
     selectFrom<TE extends keyof DB & string>(from: TE[]): SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>;
-    selectFrom<TE extends TableExpression<DB, keyof DB>>(from: TE[]): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
+    selectFrom<TE extends TableExpression<DB, never>>(from: TE[]): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
     selectFrom<TE extends keyof DB & string>(from: TE): SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>;
-    selectFrom<TE extends AnyAliasedTable<DB>>(from: TE): SelectQueryBuilder<DB & PickTableWithAlias<DB, TE>, ExtractTableAlias<DB, TE>, {}>;
-    selectFrom<TE extends TableExpression<DB, keyof DB>>(from: TE): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
+    selectFrom<TE extends AnyAliasedTable<DB>>(from: TE): SelectQueryBuilder<DB & PickTableWithAlias<DB, TE>, ExtractTableAlias<DB & PickTableWithAlias<DB, TE>, TE>, {}>;
+    selectFrom<TE extends TableExpression<DB, never>>(from: TE): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
     /**
      * Creates a `select` query builder without a `from` clause.
      *
@@ -320,31 +322,120 @@ export declare class QueryCreator<DB> {
      * ```
      */
     updateTable<TR extends keyof DB & string>(table: TR): UpdateQueryBuilder<DB, ExtractTableAlias<DB, TR>, ExtractTableAlias<DB, TR>, UpdateResult>;
-    updateTable<TR extends AnyAliasedTable<DB>>(table: TR): UpdateQueryBuilder<DB & PickTableWithAlias<DB, TR>, ExtractTableAlias<DB, TR>, ExtractTableAlias<DB, TR>, UpdateResult>;
+    updateTable<TR extends AnyAliasedTable<DB>>(table: TR): UpdateQueryBuilder<DB & PickTableWithAlias<DB, TR>, ExtractTableAlias<DB & PickTableWithAlias<DB, TR>, TR>, ExtractTableAlias<DB & PickTableWithAlias<DB, TR>, TR>, UpdateResult>;
     updateTable<TR extends TableReference<DB>>(table: TR): UpdateQueryBuilder<From<DB, TR>, FromTables<DB, never, TR>, FromTables<DB, never, TR>, UpdateResult>;
+    /**
+     * Creates a merge query.
+     *
+     * The return value of the query is a {@link MergeResult}.
+     *
+     * See the {@link MergeQueryBuilder.using} method for examples on how to specify
+     * the other table.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched((and) => and('has_pets', '!=', 'Y'))
+     *   .thenUpdateSet({ has_pets: 'Y' })
+     *   .whenNotMatched()
+     *   .thenDoNothing()
+     *   .executeTakeFirstOrThrow()
+     *
+     * console.log(result.numChangedRows)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * merge into "person"
+     * using "pet" on "pet"."owner_id" = "person"."id"
+     * when matched and "has_pets" != $1 then
+     *   update set "has_pets" = $2
+     * when not matched then
+     *   do nothing
+     * ```
+     */
+    mergeInto<TR extends keyof DB & string>(targetTable: TR): MergeQueryBuilder<DB, TR, MergeResult>;
+    mergeInto<TR extends AnyAliasedTable<DB>>(targetTable: TR): MergeQueryBuilder<DB & PickTableWithAlias<DB, TR>, ExtractTableAlias<DB & PickTableWithAlias<DB, TR>, TR>, MergeResult>;
     /**
      * Creates a `with` query (Common Table Expression).
      *
      * ### Examples
      *
+     * <!-- siteExample("cte", "Simple selects", 10) -->
+     *
+     * Common table expressions (CTE) are a great way to modularize complex queries.
+     * Essentially they allow you to run multiple separate queries within a
+     * single roundtrip to the DB.
+     *
+     * Since CTEs are a part of the main query, query optimizers inside DB
+     * engines are able to optimize the overall query. For example, postgres
+     * is able to inline the CTEs inside the using queries if it decides it's
+     * faster.
+     *
      * ```ts
-     * await db
+     * const result = await db
+     *   // Create a CTE called `jennifers` that selects all
+     *   // persons named 'Jennifer'.
      *   .with('jennifers', (db) => db
      *     .selectFrom('person')
      *     .where('first_name', '=', 'Jennifer')
      *     .select(['id', 'age'])
      *   )
+     *   // Select all rows from the `jennifers` CTE and
+     *   // further filter it.
      *   .with('adult_jennifers', (db) => db
      *     .selectFrom('jennifers')
      *     .where('age', '>', 18)
      *     .select(['id', 'age'])
      *   )
+     *   // Finally select all adult jennifers that are
+     *   // also younger than 60.
      *   .selectFrom('adult_jennifers')
      *   .where('age', '<', 60)
      *   .selectAll()
      *   .execute()
      * ```
      *
+     * <!-- siteExample("cte", "Inserts, updates and deletions", 20) -->
+     *
+     * Some databases like postgres also allow you to run other queries than selects
+     * in CTEs. On these databases CTEs are extremely powerful:
+     *
+     * ```ts
+     * const result = await db
+     *   .with('new_person', (db) => db
+     *     .insertInto('person')
+     *     .values({
+     *       first_name: 'Jennifer',
+     *       age: 35,
+     *     })
+     *     .returning('id')
+     *   )
+     *   .with('new_pet', (db) => db
+     *     .insertInto('pet')
+     *     .values({
+     *       name: 'Doggo',
+     *       species: 'dog',
+     *       is_favorite: true,
+     *       // Use the id of the person we just inserted.
+     *       owner_id: db
+     *         .selectFrom('new_person')
+     *         .select('id')
+     *     })
+     *     .returning('id')
+     *   )
+     *   .selectFrom(['new_person', 'new_pet'])
+     *   .select([
+     *     'new_person.id as person_id',
+     *     'new_pet.id as pet_id'
+     *   ])
+     *   .execute()
+     * ```
+     *
      * The CTE name can optionally specify column names in addition to
      * a name. In that case Kysely requires the expression to retun
      * rows with the same columns.