kysely 0.16.9 → 0.17.1

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

@@ -12,7 +12,6 @@ import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-b
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
-import { ParseContext } from '../parser/parse-context.js';
 import { UnionExpression } from '../parser/union-parser.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { WhereInterface } from './where-interface.js';
@@ -46,7 +45,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use `db.raw('your operator')`.
+     * you can always use `sql\`your operator\``.
      *
      * ```ts
      * const persons = await db
@@ -116,7 +115,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *
      * A `where in` query can be built by using the `in` operator and an array
      * of values. The values in the array can also be subqueries or raw
-     * instances.
+     * {@link sql} expressions.
      *
      * ```ts
      * const persons = await db
@@ -132,15 +131,17 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * If everything else fails, you can always pass {@link Kysely.raw | raw}
+     * If everything else fails, you can always use the {@link sql} tag
      * as any of the arguments, including the operator:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     db.raw('coalesce(first_name, last_name)'),
+     *     sql`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -175,24 +176,25 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * In all examples above the columns were known at compile time
-     * (except for the `raw` expressions). By default kysely only allows
-     * you to refer to columns that exist in the database **and** can be
-     * referred to in the current query and context.
+     * (except for the raw {@link sql} expressions). By default kysely only
+     * allows you to refer to columns that exist in the database **and**
+     * can be referred to in the current query and context.
      *
      * Sometimes you may want to refer to columns that come from the user
      * input and thus are not available at compile time.
      *
-     * You have two options, `db.raw` or `db.dynamic`. The example below
+     * You have two options, the {@link sql} tag or `db.dynamic`. The example below
      * uses both:
      *
      * ```ts
+     * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
-     *   .orWhere(db.raw('??', [columnFromUserInput]), '=', 2)
+     *   .orWhere(sql.id(columnFromUserInput), '=', 2)
      *   .execute()
      * ```
      */
@@ -326,13 +328,14 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
     /**
      * Adds a `where exists` clause to the query.
      *
-     * You can either use a subquery or a raw instance.
+     * You can either use a subquery or a raw {@link sql} snippet.
      *
      * ### Examples
      *
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
+     * const petName = 'Catto'
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -340,7 +343,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     .selectFrom('pet')
      *     .select('pet.id')
      *     .whereRef('person.id', '=', 'pet.owner_id')
-     *     .where('pet.name', '=', 'Catto')
+     *     .where('pet.name', '=', petName)
      *   )
      *   .execute()
      * ```
@@ -357,16 +360,16 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * )
      * ```
      *
-     * The same query as in the previous example but with using raw:
+     * The same query as in the previous example but with using raw {@link sql}:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const petName = 'Catto'
      * db.selectFrom('person')
      *   .selectAll()
      *   .whereExists(
-     *     db.raw(
-     *       '(select pet.id from pet where person.id = pet.owner_id and pet.name = ?)',
-     *       ['Catto']
-     *     )
+     *     sql`(select pet.id from pet where person.id = pet.owner_id and pet.name = ${petName})`
      *   )
      * ```
      *
@@ -449,14 +452,17 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Kysely only allows you to select columns and expressions that exist and would
      * produce valid SQL. However, Kysely is not perfect and there may be cases where
      * the type inference doesn't work and you need to override it. You can always
-     * use the {@link Kysely.dynamic | dynamic} module and {@link Kysely.raw | raw}
+     * use the {@link Kysely.dynamic | dynamic} module and the {@link sql} tag
      * to override the types.
      *
      * Select calls are additive. Calling `select('id').select('first_name')` is the
      * same as calling `select(['id', 'first_name']).
      *
      * To select all columns of the query or specific tables see the
-     * {@link SelectQueryBuilder.selectAll | selectAll} method.
+     * {@link selectAll} method.
+     *
+     * See the {@link if} method if you are looking for a way to add selections
+     * based on a runtime condition.
      *
      * ### Examples
      *
@@ -533,11 +539,13 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * from "person"
      * ```
      *
-     * You can also select subqueries and raw expressions. Note that you
+     * You can also select subqueries and raw sql expressions. Note that you
      * always need to give a name for the selections using the `as`
      * method:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db.selectFrom('person')
      *   .select([
      *     (qb) => qb
@@ -546,7 +554,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *       .select('pet.name')
      *       .limit(1)
      *       .as('pet_name')
-     *     db.raw<string>("concat(first_name, ' ', last_name)").as('full_name')
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
      *   ])
      *   .execute()
      *
@@ -568,7 +576,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * from "person"
      * ```
      *
-     * In case you use `raw` you need to specify the type of the expression
+     * In case you use the {@link sql} tag you need to specify the type of the expression
      * (in this example `string`).
      *
      * All the examples above assume you know the column names at compile time.
@@ -886,10 +894,12 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * order by "id" asc, "fn" desc
      * ```
      *
-     * The order by expression can also be a `raw` expression or a subquery
+     * The order by expression can also be a raw sql expression or a subquery
      * in addition to column references:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -899,7 +909,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     .limit(1)
      *   )
      *   .orderBy(
-     *     db.raw('concat(first_name, last_name)')
+     *     sql`concat(first_name, last_name)`
      *   )
      *   .execute()
      * ```
@@ -950,11 +960,13 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ### Examples
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .select([
      *     'first_name',
-     *     db.raw('max(id)').as('max_id')
+     *     sql`max(id)`.as('max_id')
      *   ])
      *   .groupBy('first_name')
      *   .execute()
@@ -971,14 +983,14 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * `groupBy` also accepts an array:
      *
      * ```ts
-     * const { raw } = db
+     * import { sql } from 'kysely'
      *
      * await db
      *   .selectFrom('person')
      *   .select([
      *     'first_name',
      *     'last_name',
-     *     raw('max(id)').as('max_id')
+     *     sql`max(id)`.as('max_id')
      *   ])
      *   .groupBy([
      *     'first_name',
@@ -996,20 +1008,20 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * The group by expressions can also be subqueries or
-     * raw expressions:
+     * raw sql expressions:
      *
      * ```ts
-     * const { raw } = db
+     * import { sql } from 'kysely'
      *
      * await db
      *   .selectFrom('person')
      *   .select([
      *     'first_name',
      *     'last_name',
-     *     raw('max(id)').as('max_id')
+     *     sql`max(id)`.as('max_id')
      *   ])
      *   .groupBy([
-     *     raw('concat(first_name, last_name)'),
+     *     sql`concat(first_name, last_name)`,
      *     (qb) => qb.selectFrom('pet').select('id').limit(1)
      *   ])
      *   .execute()
@@ -1243,7 +1255,6 @@ export interface SelectQueryBuilderProps {
     readonly queryId: QueryId;
     readonly queryNode: SelectQueryNode;
     readonly executor: QueryExecutor;
-    readonly parseContext: ParseContext;
 }
 /**
  * {@link SelectQueryBuilder} with an alias. The result of calling {@link SelectQueryBuilder.as}.

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

@@ -23,109 +23,109 @@ class SelectQueryBuilder {
     where(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(this.#props.parseContext, args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(args)),
         });
     }
     whereRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     orWhere(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(this.#props.parseContext, args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(args)),
         });
     }
     orWhereRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     whereExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     whereNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     orWhereExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     orWhereNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     having(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseHavingFilter)(this.#props.parseContext, args)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseHavingFilter)(args)),
         });
     }
     havingRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     orHaving(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseHavingFilter)(this.#props.parseContext, args)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseHavingFilter)(args)),
         });
     }
     orHavingRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     havingExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     havingNotExist(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     orHavingExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     orHavingNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     select(selection) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithSelections(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(this.#props.parseContext, selection)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithSelections(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(selection)),
         });
     }
     distinctOn(selection) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithDistinctOnSelections(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(this.#props.parseContext, selection)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithDistinctOnSelections(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(selection)),
         });
     }
     /**
@@ -215,25 +215,25 @@ class SelectQueryBuilder {
     innerJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'InnerJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('InnerJoin', args)),
         });
     }
     leftJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'LeftJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('LeftJoin', args)),
         });
     }
     rightJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'RightJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('RightJoin', args)),
         });
     }
     fullJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'FullJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('FullJoin', args)),
         });
     }
     /**
@@ -264,10 +264,12 @@ class SelectQueryBuilder {
      * order by "id" asc, "fn" desc
      * ```
      *
-     * The order by expression can also be a `raw` expression or a subquery
+     * The order by expression can also be a raw sql expression or a subquery
      * in addition to column references:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -277,7 +279,7 @@ class SelectQueryBuilder {
      *     .limit(1)
      *   )
      *   .orderBy(
-     *     db.raw('concat(first_name, last_name)')
+     *     sql`concat(first_name, last_name)`
      *   )
      *   .execute()
      * ```
@@ -324,13 +326,13 @@ class SelectQueryBuilder {
     orderBy(orderBy, direction) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrderByItem(this.#props.queryNode, (0, order_by_parser_js_1.parseOrderBy)(this.#props.parseContext, orderBy, direction)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrderByItem(this.#props.queryNode, (0, order_by_parser_js_1.parseOrderBy)(orderBy, direction)),
         });
     }
     groupBy(groupBy) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithGroupByItems(this.#props.queryNode, (0, group_by_parser_js_1.parseGroupBy)(this.#props.parseContext, groupBy)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithGroupByItems(this.#props.queryNode, (0, group_by_parser_js_1.parseGroupBy)(groupBy)),
         });
     }
     /**

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

@@ -12,7 +12,6 @@ import { MutationObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
-import { ParseContext } from '../parser/parse-context.js';
 import { UpdateResult } from './update-result.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { WhereInterface } from './where-interface.js';
@@ -47,7 +46,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use `db.raw('your operator')`.
+     * you can always use `sql\`your operator\``.
      *
      * ```ts
      * const persons = await db
@@ -117,7 +116,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      *
      * A `where in` query can be built by using the `in` operator and an array
      * of values. The values in the array can also be subqueries or raw
-     * instances.
+     * {@link sql} expressions.
      *
      * ```ts
      * const persons = await db
@@ -133,15 +132,17 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * If everything else fails, you can always pass {@link Kysely.raw | raw}
+     * If everything else fails, you can always use the {@link sql} tag
      * as any of the arguments, including the operator:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     db.raw('coalesce(first_name, last_name)'),
+     *     sql`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -176,24 +177,25 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * In all examples above the columns were known at compile time
-     * (except for the `raw` expressions). By default kysely only allows
-     * you to refer to columns that exist in the database **and** can be
-     * referred to in the current query and context.
+     * (except for the raw {@link sql} expressions). By default kysely only
+     * allows you to refer to columns that exist in the database **and**
+     * can be referred to in the current query and context.
      *
      * Sometimes you may want to refer to columns that come from the user
      * input and thus are not available at compile time.
      *
-     * You have two options, `db.raw` or `db.dynamic`. The example below
+     * You have two options, the {@link sql} tag or `db.dynamic`. The example below
      * uses both:
      *
      * ```ts
+     * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
-     *   .orWhere(db.raw('??', [columnFromUserInput]), '=', 2)
+     *   .orWhere(sql.id(columnFromUserInput), '=', 2)
      *   .execute()
      * ```
      */
@@ -327,13 +329,14 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
     /**
      * Adds a `where exists` clause to the query.
      *
-     * You can either use a subquery or a raw instance.
+     * You can either use a subquery or a raw {@link sql} snippet.
      *
      * ### Examples
      *
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
+     * const petName = 'Catto'
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -341,7 +344,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     .selectFrom('pet')
      *     .select('pet.id')
      *     .whereRef('person.id', '=', 'pet.owner_id')
-     *     .where('pet.name', '=', 'Catto')
+     *     .where('pet.name', '=', petName)
      *   )
      *   .execute()
      * ```
@@ -358,16 +361,16 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * )
      * ```
      *
-     * The same query as in the previous example but with using raw:
+     * The same query as in the previous example but with using raw {@link sql}:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const petName = 'Catto'
      * db.selectFrom('person')
      *   .selectAll()
      *   .whereExists(
-     *     db.raw(
-     *       '(select pet.id from pet where person.id = pet.owner_id and pet.name = ?)',
-     *       ['Catto']
-     *     )
+     *     sql`(select pet.id from pet where person.id = pet.owner_id and pet.name = ${petName})`
      *   )
      * ```
      *
@@ -526,8 +529,8 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Sets the values to update for an {@link Kysely.updateTable | update} query.
      *
      * This method takes an object whose keys are column names and values are
-     * values to update. In addition to the column's type, the values can be `raw`
-     * instances or select queries.
+     * values to update. In addition to the column's type, the values can be
+     * raw {@link sql} snippets or select queries.
      *
      * The return value of an update query is an instance of {@link UpdateResult}.
      * You can use the {@link returning} method on supported databases to get out
@@ -580,16 +583,18 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
      * ```
      *
-     * In addition to primitives, the values can also be `raw` expressions or
+     * In addition to primitives, the values can also be raw sql expressions or
      * select queries:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await db
      *   .updateTable('person')
      *   .set({
      *     first_name: 'Jennifer',
-     *     last_name: db.raw('? || ?', ['Ani', 'ston']),
-     *     age: db.selectFrom('person').select(raw('avg(age)')),
+     *     last_name: sql`${'Ani'} || ${'ston'}`,
+     *     age: db.selectFrom('person').select(sql`avg(age)`),
      *   })
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
@@ -651,7 +656,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Return arbitrary expressions:
      *
      * ```ts
-     * const { raw } = db
+     * import { sql } from 'kysely'
      *
      * const { id, full_name, first_pet_id } = await db
      *   .insertInto('person')
@@ -661,7 +666,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   })
      *   .returning([
      *     'id as id',
-     *     raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
      *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
      *   ])
      *   .executeTakeFirst()
@@ -772,5 +777,4 @@ export interface UpdateQueryBuilderProps {
     readonly queryId: QueryId;
     readonly queryNode: UpdateQueryNode;
     readonly executor: QueryExecutor;
-    readonly parseContext: ParseContext;
 }