kysely 0.19.11 → 0.20.1

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);
     /**
@@ -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);
     /**
@@ -1370,6 +1371,42 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      */
     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

@@ -15,6 +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 { ExplainNode } from '../operation-node/explain-node.js';
 export class SelectQueryBuilder {
     #props;
     constructor(props) {
@@ -627,8 +628,8 @@ export class SelectQueryBuilder {
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
     async execute() {
-        const compildQuery = this.compile();
-        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;
     }
     /**
@@ -687,6 +688,48 @@ export class SelectQueryBuilder {
             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;

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

@@ -10,6 +10,7 @@ import { preventAwait } from '../util/prevent-await.js';
 import { freeze } from '../util/object-utils.js';
 import { UpdateResult } from './update-result.js';
 import { NoResultError } from './no-result-error.js';
+import { ExplainNode } from '../operation-node/explain-node.js';
 export class UpdateQueryBuilder {
     #props;
     constructor(props) {
@@ -330,5 +331,29 @@ export class UpdateQueryBuilder {
         }
         return result;
     }
+    /**
+     * 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` = ?
+     * ```
+     */
+    async explain(format, options) {
+        const builder = new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: UpdateQueryNode.cloneWithExplain(this.#props.queryNode, ExplainNode.create(format, options)),
+        });
+        return await builder.execute();
+    }
 }
 preventAwait(UpdateQueryBuilder, "don't await UpdateQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");

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

@@ -71,6 +71,7 @@ import { CommonTableExpressionNameNode } from '../operation-node/common-table-ex
 import { SelectModifierNode } from '../operation-node/select-modifier-node.js';
 import { CreateTypeNode } from '../operation-node/create-type-node.js';
 import { DropTypeNode } from '../operation-node/drop-type-node.js';
+import { ExplainNode } from '../operation-node/explain-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -149,11 +150,17 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitSelectModifier(node: SelectModifierNode): void;
     protected visitCreateType(node: CreateTypeNode): void;
     protected visitDropType(node: DropTypeNode): void;
+    protected visitExplain(node: ExplainNode): void;
     protected append(str: string): void;
     protected appendValue(parameter: unknown): void;
     protected getLeftIdentifierWrapper(): string;
     protected getRightIdentifierWrapper(): string;
     protected getCurrentParameterPlaceholder(): string;
+    protected getLeftExplainOptionsWrapper(): string;
+    protected getExplainOptionAssignment(): string;
+    protected getExplainOptionsDelimiter(): string;
+    protected getRightExplainOptionsWrapper(): string;
+    protected sanitizeIdentifier(identifier: string): string;
     protected addParameter(parameter: unknown): void;
     protected appendImmediateValue(value: unknown): void;
 }

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

@@ -30,6 +30,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             !InsertQueryNode.is(this.parentNode) &&
             !CreateViewNode.is(this.parentNode) &&
             !UnionNode.is(this.parentNode);
+        if (this.parentNode === undefined && node.explain) {
+            this.visitNode(node.explain);
+            this.append(' ');
+        }
         if (wrapInParens) {
             this.append('(');
         }
@@ -125,6 +129,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     }
     visitInsertQuery(node) {
         const isSubQuery = this.nodeStack.find(QueryNode.is) !== node;
+        if (!isSubQuery && node.explain) {
+            this.visitNode(node.explain);
+            this.append(' ');
+        }
         if (isSubQuery) {
             this.append('(');
         }
@@ -169,6 +177,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     }
     visitDeleteQuery(node) {
         const isSubQuery = this.nodeStack.find(QueryNode.is) !== node;
+        if (!isSubQuery && node.explain) {
+            this.visitNode(node.explain);
+            this.append(' ');
+        }
         if (isSubQuery) {
             this.append('(');
         }
@@ -225,7 +237,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.append(this.getRightIdentifierWrapper());
     }
     compileUnwrappedIdentifier(node) {
-        this.append(node.identifier);
+        if (!isString(node.identifier)) {
+            throw new Error('a non-string identifier was passed to compileUnwrappedIdentifier.');
+        }
+        this.append(this.sanitizeIdentifier(node.identifier));
     }
     visitFilter(node) {
         if (node.left) {
@@ -309,6 +324,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     }
     visitCreateTable(node) {
         this.append('create ');
+        if (node.frontModifiers) {
+            this.compileList(node.frontModifiers, ' ');
+            this.append(' ');
+        }
         if (node.temporary) {
             this.append('temporary ');
         }
@@ -324,6 +343,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' on commit ');
             this.append(node.onCommit);
         }
+        if (node.endModifiers) {
+            this.append(' ');
+            this.compileList(node.endModifiers, ' ');
+        }
     }
     visitColumnDefinition(node) {
         this.visitNode(node.column);
@@ -410,6 +433,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     }
     visitUpdateQuery(node) {
         const isSubQuery = this.nodeStack.find(QueryNode.is) !== node;
+        if (!isSubQuery && node.explain) {
+            this.visitNode(node.explain);
+            this.append(' ');
+        }
         if (isSubQuery) {
             this.append('(');
         }
@@ -804,6 +831,25 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         }
         this.visitNode(node.name);
     }
+    visitExplain(node) {
+        this.append('explain');
+        if (node.options || node.format) {
+            this.append(' ');
+            this.append(this.getLeftExplainOptionsWrapper());
+            if (node.options) {
+                this.visitNode(node.options);
+                if (node.format) {
+                    this.append(this.getExplainOptionsDelimiter());
+                }
+            }
+            if (node.format) {
+                this.append('format');
+                this.append(this.getExplainOptionAssignment());
+                this.append(node.format);
+            }
+            this.append(this.getRightExplainOptionsWrapper());
+        }
+    }
     append(str) {
         this.#sql += str;
     }
@@ -820,6 +866,33 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     getCurrentParameterPlaceholder() {
         return '$' + this.numParameters;
     }
+    getLeftExplainOptionsWrapper() {
+        return '(';
+    }
+    getExplainOptionAssignment() {
+        return ' ';
+    }
+    getExplainOptionsDelimiter() {
+        return ', ';
+    }
+    getRightExplainOptionsWrapper() {
+        return ')';
+    }
+    sanitizeIdentifier(identifier) {
+        const leftWrap = this.getLeftIdentifierWrapper();
+        const rightWrap = this.getRightIdentifierWrapper();
+        let sanitized = '';
+        for (const c of identifier) {
+            sanitized += c;
+            if (c === leftWrap) {
+                sanitized += leftWrap;
+            }
+            else if (c === rightWrap) {
+                sanitized += rightWrap;
+            }
+        }
+        return sanitized;
+    }
     addParameter(parameter) {
         this.#parameters.push(parameter);
     }

package/dist/esm/raw-builder/sql.d.ts

@@ -1,5 +1,101 @@
 import { RawBuilder } from './raw-builder.js';
 export interface Sql {
+    /**
+     * Template tag for creating raw SQL snippets and queries.
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const id = 123
+     *
+     * const snippet = sql<Person[]>`select * from person where id = ${id}`
+     * ```
+     *
+     * Substitutions (the things inside `${}`) are automatically passed to the database
+     * as parameters and are NOT interpolated to the SQL string. There's no need to worry
+     * about SQL injection vulnerabilities.
+     *
+     * If you need your substitutions to be interpreted as identifiers, value literals or
+     * lists of things, see the {@link Sql.ref}, {@link Sql.table}, {@link Sql.id},
+     * {@link Sql.literal}, {@link Sql.raw} and {@link Sql.join} functions.
+     *
+     * You can pass sql snippets returned by the `sql` tag pretty much anywhere. Whenever
+     * something can't be done using the Kysely API, you should be able to drop down to
+     * raw SQL using the `sql` tag. Here's an example query that uses raw sql in a bunch
+     * of methods:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     // If you use `sql` in a select statement, remember to call the `as`
+     *     // method to give it an alias. Otherwise Kysely is not able to add
+     *     // the column to the result type.
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
+     *   )
+     *   .where(sql`birthdate between ${date1} and ${date2}`)
+     *   // Here we assume we have list of nicknames for the person
+     *   // (a list of strings) and we use the PostgreSQL `@>` operator
+     *   // to test if all of them are valid nicknames for the user.
+     *   .where('nicknames', '@>', sql`ARRAY[${sql.join(nicknames)}]`)
+     *   .orderBy(sql`concat(first_name, ' ', last_name)`)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select concat(first_name, ' ', last_name) as "full_name"
+     * from "person"
+     * where birthdate between $1 and $2
+     * and "nicknames" @> ARRAY[$3, $4, $5, $6, $7, $8, $9, $10]
+     * order by concat(first_name, ' ', last_name)
+     * ```
+     *
+     * SQL snippets can be executed by calling the `execute` method and passing a `Kysely`
+     * instance as the only argument:
+     *
+     * ```ts
+     * const result = await sql<Person[]>`select * from person`.execute(db)
+     * ```
+     *
+     * You can merge other `sql` expressions and queries using substitutions:
+     *
+     * ```ts
+     * const petName = db.selectFrom('pet').select('name').limit(1)
+     * const fullName = sql`concat(first_name, ' ', last_name)`
+     *
+     * sql`
+     *   select ${fullName} as full_name, ${petName} as pet_name
+     *   from person
+     * `
+     * ```
+     *
+     * Substitutions also handle {@link ExpressionBuilder.ref},
+     * {@link DynamicModule.ref} and pretty much anything else you
+     * throw at it. Here's an example of calling a function in a
+     * type-safe way:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select([
+     *     'first_name',
+     *     'last_name',
+     *     (eb) => {
+     *       // The `eb.ref` method is type-safe and only accepts
+     *       // column references that are possible.
+     *       const firstName = eb.ref('first_name')
+     *       const lastName = eb.ref('last_name')
+     *
+     *       const fullName = sql<string>`concat(${firstName}, ' ', ${lastName})`
+     *       return fullName.as('full_name')
+     *     }
+     *   ])
+     * ```
+     *
+     * don't know if that amount of ceremony is worth the small increase in
+     * type-safety though... But it's possible.
+     */
     <T = unknown>(sqlFragments: TemplateStringsArray, ...parameters: unknown[]): RawBuilder<T>;
     /**
      * This can be used to add runtime column references to SQL snippets.
@@ -232,100 +328,4 @@ export interface Sql {
      */
     join(array: unknown[], separator?: RawBuilder<any>): RawBuilder<unknown>;
 }
-/**
- * Template tag for creating raw SQL snippets and queries.
- *
- * ```ts
- * import { sql } from 'kysely'
- *
- * const id = 123
- *
- * const snippet = sql<Person[]>`select * from person where id = ${id}`
- * ```
- *
- * Substitutions (the things inside `${}`) are automatically passed to the database
- * as parameters and are NOT interpolated to the SQL string. There's no need to worry
- * about SQL injection vulnerabilities.
- *
- * If you need your substitutions to be interpreted as identifiers, value literals or
- * lists of things, see the {@link Sql.ref}, {@link Sql.table}, {@link Sql.id},
- * {@link Sql.literal}, {@link Sql.raw} and {@link Sql.join} functions.
- *
- * You can pass sql snippets returned by the `sql` tag pretty much anywhere. Whenever
- * something can't be done using the Kysely API, you should be able to drop down to
- * raw SQL using the `sql` tag. Here's an example query that uses raw sql in a bunch
- * of methods:
- *
- * ```ts
- * const persons = await db
- *   .selectFrom('person')
- *   .select(
- *     // If you use `sql` in a select statement, remember to call the `as`
- *     // method to give it an alias. Otherwise Kysely is not able to add
- *     // the column to the result type.
- *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
- *   )
- *   .where(sql`birthdate between ${date1} and ${date2}`)
- *   // Here we assume we have list of nicknames for the person
- *   // (a list of strings) and we use the PostgreSQL `@>` operator
- *   // to test if all of them are valid nicknames for the user.
- *   .where('nicknames', '@>', sql`ARRAY[${sql.join(nicknames)}]`)
- *   .orderBy(sql`concat(first_name, ' ', last_name)`)
- *   .execute()
- * ```
- *
- * The generated SQL (PostgreSQL):
- *
- * ```sql
- * select concat(first_name, ' ', last_name) as "full_name"
- * from "person"
- * where birthdate between $1 and $2
- * and "nicknames" @> ARRAY[$3, $4, $5, $6, $7, $8, $9, $10]
- * order by concat(first_name, ' ', last_name)
- * ```
- *
- * SQL snippets can be executed by calling the `execute` method and passing a `Kysely`
- * instance as the only argument:
- *
- * ```ts
- * const result = await sql<Person[]>`select * from person`.execute(db)
- * ```
- *
- * You can merge other `sql` expressions and queries using substitutions:
- *
- * ```ts
- * const petName = db.selectFrom('pet').select('name').limit(1)
- * const fullName = sql`concat(first_name, ' ', last_name)`
- *
- * sql`
- *   select ${fullName} as full_name, ${petName} as pet_name
- *   from person
- * `
- * ```
- *
- * Substitutions also handle {@link ExpressionBuilder.ref},
- * {@link DynamicModule.ref} and pretty much anything else you
- * throw at it. Here's an example of calling a function in a
- * type-safe way:
- *
- * ```ts
- * db.selectFrom('person')
- *   .select([
- *     'first_name',
- *     'last_name',
- *     (eb) => {
- *       // The `eb.ref` method is type-safe and only accepts
- *       // column references that are possible.
- *       const firstName = eb.ref('first_name')
- *       const lastName = eb.ref('last_name')
- *
- *       const fullName = sql<string>`concat(${firstName}, ' ', ${lastName})`
- *       return fullName.as('full_name')
- *     }
- *   ])
- * ```
- *
- * don't know if that amount of ceremony is worth the small increase in
- * type-safety though... But it's possible.
- */
 export declare const sql: Sql;