kysely 0.19.10 → 0.20.0

package/dist/esm/operation-node/operation-node-transformer.js

@@ -102,6 +102,7 @@ export class OperationNodeTransformer {
         SelectModifierNode: this.transformSelectModifier.bind(this),
         CreateTypeNode: this.transformCreateType.bind(this),
         DropTypeNode: this.transformDropType.bind(this),
+        ExplainNode: this.transformExplain.bind(this),
     });
     transformNode = (node) => {
         if (!node) {
@@ -135,6 +136,7 @@ export class OperationNodeTransformer {
             with: this.transformNode(node.with),
             having: this.transformNode(node.having),
             union: this.transformNodeList(node.union),
+            explain: this.transformNode(node.explain),
         });
     }
     transformSelection(node) {
@@ -242,6 +244,8 @@ export class OperationNodeTransformer {
             onDuplicateKey: this.transformNode(node.onDuplicateKey),
             with: this.transformNode(node.with),
             ignore: node.ignore,
+            replace: node.replace,
+            explain: this.transformNode(node.explain),
         });
     }
     transformValues(node) {
@@ -260,6 +264,7 @@ export class OperationNodeTransformer {
             with: this.transformNode(node.with),
             orderBy: this.transformNode(node.orderBy),
             limit: this.transformNode(node.limit),
+            explain: this.transformNode(node.explain),
         });
     }
     transformReturning(node) {
@@ -277,6 +282,8 @@ export class OperationNodeTransformer {
             temporary: node.temporary,
             ifNotExists: node.ifNotExists,
             onCommit: node.onCommit,
+            frontModifiers: this.transformNodeList(node.frontModifiers),
+            endModifiers: this.transformNodeList(node.endModifiers),
         });
     }
     transformColumnDefinition(node) {
@@ -343,6 +350,7 @@ export class OperationNodeTransformer {
             updates: this.transformNodeList(node.updates),
             returning: this.transformNode(node.returning),
             with: this.transformNode(node.with),
+            explain: this.transformNode(node.explain),
         });
     }
     transformColumnUpdate(node) {
@@ -641,4 +649,11 @@ export class OperationNodeTransformer {
         // An Object.freezed leaf node. No need to clone.
         return node;
     }
+    transformExplain(node) {
+        return requireAllProps({
+            kind: 'ExplainNode',
+            format: node.format,
+            options: this.transformNode(node.options),
+        });
+    }
 }

package/dist/esm/operation-node/operation-node-visitor.d.ts

@@ -68,6 +68,7 @@ import { ValuesNode } from './values-node.js';
 import { SelectModifierNode } from './select-modifier-node.js';
 import { CreateTypeNode } from './create-type-node.js';
 import { DropTypeNode } from './drop-type-node.js';
+import { ExplainNode } from './explain-node.js';
 export declare abstract class OperationNodeVisitor {
     #private;
     protected readonly nodeStack: OperationNode[];
@@ -142,4 +143,5 @@ export declare abstract class OperationNodeVisitor {
     protected abstract visitSelectModifier(node: SelectModifierNode): void;
     protected abstract visitCreateType(node: CreateTypeNode): void;
     protected abstract visitDropType(node: DropTypeNode): void;
+    protected abstract visitExplain(node: ExplainNode): void;
 }

package/dist/esm/operation-node/operation-node-visitor.js

@@ -75,6 +75,7 @@ export class OperationNodeVisitor {
         SelectModifierNode: this.visitSelectModifier.bind(this),
         CreateTypeNode: this.visitCreateType.bind(this),
         DropTypeNode: this.visitDropType.bind(this),
+        ExplainNode: this.visitExplain.bind(this),
     });
     visitNode = (node) => {
         this.nodeStack.push(node);

package/dist/esm/operation-node/operation-node.d.ts

@@ -1,4 +1,4 @@
-export declare type OperationNodeKind = 'IdentifierNode' | 'RawNode' | 'SelectQueryNode' | 'SelectionNode' | 'ReferenceNode' | 'ColumnNode' | 'TableNode' | 'AliasNode' | 'FromNode' | 'SelectAllNode' | 'FilterNode' | 'AndNode' | 'OrNode' | 'ParensNode' | 'ValueNode' | 'ValueListNode' | 'PrimitiveValueListNode' | 'JoinNode' | 'OperatorNode' | 'WhereNode' | 'InsertQueryNode' | 'DeleteQueryNode' | 'ReturningNode' | 'CreateTableNode' | 'ColumnDefinitionNode' | 'AddColumnNode' | 'DropTableNode' | 'DataTypeNode' | 'OrderByNode' | 'OrderByItemNode' | 'GroupByNode' | 'GroupByItemNode' | 'UpdateQueryNode' | 'ColumnUpdateNode' | 'LimitNode' | 'OffsetNode' | 'OnConflictNode' | 'OnDuplicateKeyNode' | 'CreateIndexNode' | 'DropIndexNode' | 'ListNode' | 'ReferencesNode' | 'PrimaryKeyConstraintNode' | 'UniqueConstraintNode' | 'CheckConstraintNode' | 'ForeignKeyConstraintNode' | 'WithNode' | 'CommonTableExpressionNode' | 'HavingNode' | 'CreateSchemaNode' | 'DropSchemaNode' | 'AlterTableNode' | 'ModifyColumnNode' | 'DropColumnNode' | 'RenameColumnNode' | 'AlterColumnNode' | 'AddConstraintNode' | 'DropConstraintNode' | 'UnionNode' | 'CreateViewNode' | 'DropViewNode' | 'GeneratedNode' | 'DefaultValueNode' | 'OnNode' | 'ValuesNode' | 'CommonTableExpressionNameNode' | 'SelectModifierNode' | 'CreateTypeNode' | 'DropTypeNode';
+export declare type OperationNodeKind = 'IdentifierNode' | 'RawNode' | 'SelectQueryNode' | 'SelectionNode' | 'ReferenceNode' | 'ColumnNode' | 'TableNode' | 'AliasNode' | 'FromNode' | 'SelectAllNode' | 'FilterNode' | 'AndNode' | 'OrNode' | 'ParensNode' | 'ValueNode' | 'ValueListNode' | 'PrimitiveValueListNode' | 'JoinNode' | 'OperatorNode' | 'WhereNode' | 'InsertQueryNode' | 'DeleteQueryNode' | 'ReturningNode' | 'CreateTableNode' | 'ColumnDefinitionNode' | 'AddColumnNode' | 'DropTableNode' | 'DataTypeNode' | 'OrderByNode' | 'OrderByItemNode' | 'GroupByNode' | 'GroupByItemNode' | 'UpdateQueryNode' | 'ColumnUpdateNode' | 'LimitNode' | 'OffsetNode' | 'OnConflictNode' | 'OnDuplicateKeyNode' | 'CreateIndexNode' | 'DropIndexNode' | 'ListNode' | 'ReferencesNode' | 'PrimaryKeyConstraintNode' | 'UniqueConstraintNode' | 'CheckConstraintNode' | 'ForeignKeyConstraintNode' | 'WithNode' | 'CommonTableExpressionNode' | 'HavingNode' | 'CreateSchemaNode' | 'DropSchemaNode' | 'AlterTableNode' | 'ModifyColumnNode' | 'DropColumnNode' | 'RenameColumnNode' | 'AlterColumnNode' | 'AddConstraintNode' | 'DropConstraintNode' | 'UnionNode' | 'CreateViewNode' | 'DropViewNode' | 'GeneratedNode' | 'DefaultValueNode' | 'OnNode' | 'ValuesNode' | 'CommonTableExpressionNameNode' | 'SelectModifierNode' | 'CreateTypeNode' | 'DropTypeNode' | 'ExplainNode';
 export interface OperationNode {
     readonly kind: OperationNodeKind;
 }

package/dist/esm/operation-node/references-node.d.ts

@@ -1,7 +1,9 @@
 import { OperationNode } from './operation-node.js';
 import { ColumnNode } from './column-node.js';
 import { TableNode } from './table-node.js';
-export declare type OnModifyForeignAction = 'no action' | 'restrict' | 'cascade' | 'set null' | 'set default';
+import { ArrayItemType } from '../util/type-utils.js';
+export declare const ON_MODIFY_FOREIGN_ACTIONS: readonly ["no action", "restrict", "cascade", "set null", "set default"];
+export declare type OnModifyForeignAction = ArrayItemType<typeof ON_MODIFY_FOREIGN_ACTIONS>;
 export interface ReferencesNode extends OperationNode {
     readonly kind: 'ReferencesNode';
     readonly table: TableNode;

package/dist/esm/operation-node/references-node.js

@@ -1,5 +1,12 @@
 /// <reference types="./references-node.d.ts" />
 import { freeze } from '../util/object-utils.js';
+export const ON_MODIFY_FOREIGN_ACTIONS = [
+    'no action',
+    'restrict',
+    'cascade',
+    'set null',
+    'set default',
+];
 /**
  * @internal
  */

package/dist/esm/operation-node/select-query-node.d.ts

@@ -14,6 +14,7 @@ import { WhereNode } from './where-node.js';
 import { WithNode } from './with-node.js';
 import { UnionNode } from './union-node.js';
 import { SelectModifierNode } from './select-modifier-node.js';
+import { ExplainNode } from './explain-node.js';
 export interface SelectQueryNode extends OperationNode {
     readonly kind: 'SelectQueryNode';
     readonly from: FromNode;
@@ -30,6 +31,7 @@ export interface SelectQueryNode extends OperationNode {
     readonly with?: WithNode;
     readonly having?: HavingNode;
     readonly union?: ReadonlyArray<UnionNode>;
+    readonly explain?: ExplainNode;
 }
 /**
  * @internal
@@ -48,4 +50,5 @@ export declare const SelectQueryNode: Readonly<{
     cloneWithHaving(selectNode: SelectQueryNode, filter: FilterExpressionNode): SelectQueryNode;
     cloneWithOrHaving(selectNode: SelectQueryNode, filter: FilterExpressionNode): SelectQueryNode;
     cloneWithUnion(selectNode: SelectQueryNode, union: UnionNode): SelectQueryNode;
+    cloneWithExplain(selectNode: SelectQueryNode, explain: ExplainNode): SelectQueryNode;
 }>;

package/dist/esm/operation-node/select-query-node.js

@@ -102,4 +102,10 @@ export const SelectQueryNode = freeze({
                 : freeze([union]),
         });
     },
+    cloneWithExplain(selectNode, explain) {
+        return freeze({
+            ...selectNode,
+            explain,
+        });
+    },
 });

package/dist/esm/operation-node/update-query-node.d.ts

@@ -8,6 +8,7 @@ import { ValueListNode } from './value-list-node.js';
 import { WhereNode } from './where-node.js';
 import { WithNode } from './with-node.js';
 import { FromNode } from './from-node.js';
+import { ExplainNode } from './explain-node.js';
 export declare type UpdateValuesNode = ValueListNode | PrimitiveValueListNode;
 export interface UpdateQueryNode extends OperationNode {
     readonly kind: 'UpdateQueryNode';
@@ -18,6 +19,7 @@ export interface UpdateQueryNode extends OperationNode {
     readonly updates?: ReadonlyArray<ColumnUpdateNode>;
     readonly returning?: ReturningNode;
     readonly with?: WithNode;
+    readonly explain?: ExplainNode;
 }
 /**
  * @internal
@@ -27,4 +29,5 @@ export declare const UpdateQueryNode: Readonly<{
     create(table: TableExpressionNode, withNode?: WithNode): UpdateQueryNode;
     cloneWithFromItems(updateQuery: UpdateQueryNode, fromItems: ReadonlyArray<TableExpressionNode>): UpdateQueryNode;
     cloneWithUpdates(updateQuery: UpdateQueryNode, updates: ReadonlyArray<ColumnUpdateNode>): UpdateQueryNode;
+    cloneWithExplain(updateQuery: UpdateQueryNode, explain: ExplainNode): UpdateQueryNode;
 }>;

package/dist/esm/operation-node/update-query-node.js

@@ -31,4 +31,10 @@ export const UpdateQueryNode = freeze({
                 : updates,
         });
     },
+    cloneWithExplain(updateQuery, explain) {
+        return freeze({
+            ...updateQuery,
+            explain,
+        });
+    },
 });

package/dist/esm/parser/on-commit-action-parse.d.ts

@@ -0,0 +1,2 @@
+import { OnCommitAction } from '../operation-node/create-table-node.js';
+export declare function parseOnCommitAction(action: OnCommitAction): OnCommitAction;

package/dist/esm/parser/on-commit-action-parse.js

@@ -0,0 +1,8 @@
+/// <reference types="./on-commit-action-parse.d.ts" />
+import { ON_COMMIT_ACTIONS, } from '../operation-node/create-table-node.js';
+export function parseOnCommitAction(action) {
+    if (ON_COMMIT_ACTIONS.includes(action)) {
+        return action;
+    }
+    throw new Error(`invalid OnCommitAction ${action}`);
+}

package/dist/esm/parser/on-modify-action-parser.d.ts

@@ -0,0 +1,2 @@
+import { OnModifyForeignAction } from '../operation-node/references-node.js';
+export declare function parseOnModifyForeignAction(action: OnModifyForeignAction): OnModifyForeignAction;

package/dist/esm/parser/on-modify-action-parser.js

@@ -0,0 +1,8 @@
+/// <reference types="./on-modify-action-parser.d.ts" />
+import { ON_MODIFY_FOREIGN_ACTIONS, } from '../operation-node/references-node.js';
+export function parseOnModifyForeignAction(action) {
+    if (ON_MODIFY_FOREIGN_ACTIONS.includes(action)) {
+        return action;
+    }
+    throw new Error(`invalid OnModifyForeignAction ${action}`);
+}

package/dist/esm/query-builder/delete-query-builder.d.ts

@@ -20,7 +20,8 @@ import { Selectable } from '../util/column-type.js';
 import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-by-parser.js';
 import { AliasedQueryBuilder } from './select-query-builder.js';
 import { AliasedRawBuilder } from '../raw-builder/raw-builder.js';
-export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
+import { Explainable, ExplainFormat } from '../util/explainable.js';
+export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable, Explainable {
     #private;
     constructor(props: DeleteQueryBuilderProps);
     /**
@@ -744,6 +745,23 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * error.
      */
     executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    /**
+     * Executes query with `explain` statement before `delete` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .deleteFrom('person')
+     *  .where('id', '=', 123)
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json delete from `person` where `id` = ?
+     * ```
+     */
+    explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: AnyRawBuilder): Promise<ER[]>;
 }
 export interface DeleteQueryBuilderProps {
     readonly queryId: QueryId;

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

@@ -10,6 +10,7 @@ import { DeleteResult } from './delete-result.js';
 import { DeleteQueryNode } from '../operation-node/delete-query-node.js';
 import { LimitNode } from '../operation-node/limit-node.js';
 import { parseOrderBy, } from '../parser/order-by-parser.js';
+import { ExplainNode } from '../operation-node/explain-node.js';
 export class DeleteQueryBuilder {
     #props;
     constructor(props) {
@@ -293,5 +294,28 @@ export class DeleteQueryBuilder {
         }
         return result;
     }
+    /**
+     * Executes query with `explain` statement before `delete` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .deleteFrom('person')
+     *  .where('id', '=', 123)
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json delete from `person` where `id` = ?
+     * ```
+     */
+    async explain(format, options) {
+        const builder = new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: DeleteQueryNode.cloneWithExplain(this.#props.queryNode, ExplainNode.create(format, options)),
+        });
+        return await builder.execute();
+    }
 }
 preventAwait(DeleteQueryBuilder, "don't await DeleteQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");

package/dist/esm/query-builder/function-builder.d.ts

@@ -85,7 +85,7 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    avg<O extends number | string, C extends StringReference<DB, TB> = any>(column: C): RawBuilder<O>;
+    avg<O extends number | string, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): RawBuilder<O>;
     /**
      * Calls the `sum` function for the column given as the argument.
      *
@@ -107,7 +107,7 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    sum<O extends number | string | bigint, C extends StringReference<DB, TB> = any>(column: C): RawBuilder<O>;
+    sum<O extends number | string | bigint, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): RawBuilder<O>;
     /**
      * Calls the `count` function for the column given as the argument.
      *
@@ -129,5 +129,5 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    count<O extends number | string | bigint, C extends StringReference<DB, TB> = any>(column: C): RawBuilder<O>;
+    count<O extends number | string | bigint, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): RawBuilder<O>;
 }

package/dist/esm/query-builder/insert-query-builder.d.ts

@@ -3,7 +3,7 @@ import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { SelectExpression } from '../parser/select-parser.js';
 import { InsertObject } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
-import { MergePartial, SingleResultType } from '../util/type-utils.js';
+import { AnyRawBuilder, MergePartial, SingleResultType } from '../util/type-utils.js';
 import { MutationObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
@@ -16,7 +16,8 @@ import { ComplexExpression } from '../parser/complex-expression-parser.js';
 import { ReturningInterface } from './returning-interface.js';
 import { OnConflictBuilder, OnConflictDoNothingBuilder, OnConflictUpdateBuilder } from './on-conflict-builder.js';
 import { Selectable } from '../util/column-type.js';
-export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
+import { Explainable, ExplainFormat } from '../util/explainable.js';
+export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable, Explainable {
     #private;
     constructor(props: InsertQueryBuilderProps);
     /**
@@ -43,7 +44,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *
      * Insert a row into `person`:
      * ```ts
-     * const id = await db
+     * const result = await db
      *   .insertInto('person')
      *   .values({
      *     first_name: 'Jennifer',
@@ -541,6 +542,23 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * error.
      */
     executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    /**
+     * Executes query with `explain` statement before `insert` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .insertInto('person')
+     *  .values(values)
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json insert into `person` (`id`, `first_name`, `last_name`) values (?, ?, ?) (?, ?, ?)
+     * ```
+     */
+    explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: AnyRawBuilder): Promise<ER[]>;
 }
 export interface InsertQueryBuilderProps {
     readonly queryId: QueryId;

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

@@ -13,6 +13,7 @@ import { parseComplexExpression, } from '../parser/complex-expression-parser.js'
 import { ColumnNode } from '../operation-node/column-node.js';
 import { OnConflictBuilder, } from './on-conflict-builder.js';
 import { OnConflictNode } from '../operation-node/on-conflict-node.js';
+import { ExplainNode } from '../operation-node/explain-node.js';
 export class InsertQueryBuilder {
     #props;
     constructor(props) {
@@ -444,5 +445,30 @@ export class InsertQueryBuilder {
         }
         return result;
     }
+    /**
+     * Executes query with `explain` statement before `insert` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .insertInto('person')
+     *  .values(values)
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json insert into `person` (`id`, `first_name`, `last_name`) values (?, ?, ?) (?, ?, ?)
+     * ```
+     */
+    async explain(format, options) {
+        const builder = new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                explain: ExplainNode.create(format, options),
+            }),
+        });
+        return await builder.execute();
+    }
 }
 preventAwait(InsertQueryBuilder, "don't await InsertQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");

package/dist/esm/query-builder/select-query-builder.d.ts

@@ -18,7 +18,8 @@ import { WhereInterface } from './where-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
 import { HavingInterface } from './having-interface.js';
 import { AliasedRawBuilder } from '../raw-builder/raw-builder.js';
-export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, HavingInterface<DB, TB>, OperationNodeSource, Compilable {
+import { Explainable, ExplainFormat } from '../util/explainable.js';
+export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, HavingInterface<DB, TB>, OperationNodeSource, Compilable, Explainable {
     #private;
     constructor(props: SelectQueryBuilderProps);
     /**
@@ -1343,6 +1344,69 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * error.
      */
     executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    /**
+     * Executes the query and streams the rows.
+     *
+     * The optional argument `chunkSize` defines how many rows to fetch from the database
+     * at a time. It only affects some dialects like PostgreSQL that support it.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const stream = db.
+     *   .selectFrom('person')
+     *   .select(['first_name', 'last_name'])
+     *   .where('gender', '=', 'other')
+     *   .stream()
+     *
+     * for await (const person of stream) {
+     *   console.log(person.first_name)
+     *
+     *   if (person.last_name === 'Something') {
+     *     // Breaking or returning before the stream has ended will release
+     *     // the database connection and invalidate the stream.
+     *     break
+     *   }
+     * }
+     * ```
+     */
+    stream(chunkSize?: number): AsyncIterableIterator<O>;
+    /**
+     * Executes query with `explain` statement before `select` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json select * from `person` where `gender` = ?
+     * ```
+     *
+     * You can also execute `explain analyze` statements.
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json', sql`analyze`)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * explain (analyze, format json) select * from "person" where "gender" = $1
+     * ```
+     */
+    explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: AnyRawBuilder): Promise<ER[]>;
 }
 export interface SelectQueryBuilderProps {
     readonly queryId: QueryId;

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

@@ -1,5 +1,6 @@
 /// <reference types="./select-query-builder.d.ts" />
 import { AliasNode } from '../operation-node/alias-node.js';
+import { SelectModifierNode } from '../operation-node/select-modifier-node.js';
 import { parseJoin, } from '../parser/join-parser.js';
 import { parseSelectExpressionOrList, parseSelectAll, } from '../parser/select-parser.js';
 import { parseExistFilter, parseReferenceFilter, parseWhereFilter, parseHavingFilter, parseNotExistFilter, } from '../parser/filter-parser.js';
@@ -14,7 +15,7 @@ import { parseGroupBy } from '../parser/group-by-parser.js';
 import { parseUnion } from '../parser/union-parser.js';
 import { NoResultError } from './no-result-error.js';
 import { IdentifierNode } from '../operation-node/identifier-node.js';
-import { SelectModifierNode } from '../operation-node/select-modifier-node.js';
+import { ExplainNode } from '../operation-node/explain-node.js';
 export class SelectQueryBuilder {
     #props;
     constructor(props) {
@@ -627,9 +628,8 @@ export class SelectQueryBuilder {
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
     async execute() {
-        const compildQuery = this.compile();
-        const query = compildQuery.query;
-        const result = await this.#props.executor.executeQuery(compildQuery, this.#props.queryId);
+        const compiledQuery = this.compile();
+        const result = await this.#props.executor.executeQuery(compiledQuery, this.#props.queryId);
         return result.rows;
     }
     /**
@@ -655,6 +655,81 @@ export class SelectQueryBuilder {
         }
         return result;
     }
+    /**
+     * Executes the query and streams the rows.
+     *
+     * The optional argument `chunkSize` defines how many rows to fetch from the database
+     * at a time. It only affects some dialects like PostgreSQL that support it.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const stream = db.
+     *   .selectFrom('person')
+     *   .select(['first_name', 'last_name'])
+     *   .where('gender', '=', 'other')
+     *   .stream()
+     *
+     * for await (const person of stream) {
+     *   console.log(person.first_name)
+     *
+     *   if (person.last_name === 'Something') {
+     *     // Breaking or returning before the stream has ended will release
+     *     // the database connection and invalidate the stream.
+     *     break
+     *   }
+     * }
+     * ```
+     */
+    async *stream(chunkSize = 100) {
+        const compildQuery = this.compile();
+        const stream = this.#props.executor.stream(compildQuery, chunkSize, this.#props.queryId);
+        for await (const item of stream) {
+            yield* item.rows;
+        }
+    }
+    /**
+     * Executes query with `explain` statement before `select` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json select * from `person` where `gender` = ?
+     * ```
+     *
+     * You can also execute `explain analyze` statements.
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json', sql`analyze`)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * explain (analyze, format json) select * from "person" where "gender" = $1
+     * ```
+     */
+    async explain(format, options) {
+        const builder = new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithExplain(this.#props.queryNode, ExplainNode.create(format, options)),
+        });
+        return await builder.execute();
+    }
 }
 preventAwait(SelectQueryBuilder, "don't await SelectQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");
 /**

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

@@ -20,7 +20,8 @@ import { NoResultErrorConstructor } from './no-result-error.js';
 import { Selectable } from '../util/column-type.js';
 import { AliasedQueryBuilder } from './select-query-builder.js';
 import { AliasedRawBuilder } from '../raw-builder/raw-builder.js';
-export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
+import { Explainable, ExplainFormat } from '../util/explainable.js';
+export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable, Explainable {
     #private;
     constructor(props: UpdateQueryBuilderProps);
     /**
@@ -809,6 +810,24 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * error.
      */
     executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    /**
+     * Executes query with `explain` statement before `update` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .updateTable('person')
+     *  .set(updates)
+     *  .where('id', '=', 123)
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json update `person` set `first_name` = ?, `last_name` = ? where `id` = ?
+     * ```
+     */
+    explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: AnyRawBuilder): Promise<ER[]>;
 }
 export interface UpdateQueryBuilderProps {
     readonly queryId: QueryId;