pqb 0.38.6 → 0.38.7

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { PoolConfig, Pool, PoolClient } from 'pg';
 import * as orchid_core from 'orchid-core';
-import { QueryResultRow, AdapterConfigBase, AdapterBase, QueryInput, SingleSqlItem, Sql, RecordUnknown, RecordKeyTrue, EmptyObject, QueryBaseCommon, QueryColumns, QueryMetaBase, QueryReturnType, QueryThen, Expression, MaybeArray, TemplateLiteralArgs, QueryColumn, MaybePromise, FnUnknownToUnknown, RecordString, ColumnsShapeBase, ColumnsParsers, PickQueryTable, BatchParsers, HookSelect, QueryLogObject, QueryLogger, QueryDataTransform, ExpressionChain, PickQueryShape, PickQueryTableMetaResult, EmptyTuple, PickQueryMeta, PickQueryMetaResultReturnType, QueryColumnToNullable, SelectableBase, PickQueryMetaShape, PickQueryTableMetaResultShape, PickQueryMetaResultWindows, PickOutputTypeAndOperators, PickQueryResult, ExpressionData, ValExpression, PickOutputType, SQLQueryArgs, ColumnSchemaConfig, DateColumnData, ColumnToCodeCtx, Code, TimeInterval, ColumnTypeSchemaArg, ColumnDataBase, ArrayMethodsData, RawSQLBase, RawSQLValues, ExpressionTypeMethod, DynamicSQLArg, StaticSQLArgs, ForeignKeyTable, ColumnNameOfTable, BaseNumberData, PickColumnBaseData, ColumnWithDefault, StringTypeData, PrimaryKeyColumn, ParseColumn, EncodeColumn, QueryColumnsInit, QueryLogOptions, DefaultSelectColumns, DbBase, QueryCatch, TransactionState, ColumnTypeBase, PickQueryUniqueProperties, PickQueryMetaResult, IsQuery, PickQueryTableMetaResultInputType, getValueKey, PickQueryResultUniqueColumns, QueryInternalBase, PickQueryReturnType, PickType, ColumnShapeOutput, OperatorsNullable, PickQueryMetaReturnType, UniqueColumn, TimestampHelpers, Codes, ColumnDataCheckBase } from 'orchid-core';
+import { QueryResultRow, AdapterConfigBase, AdapterBase, QueryInput, SingleSqlItem, Sql, RecordUnknown, RecordKeyTrue, EmptyObject, QueryBaseCommon, QueryColumns, QueryMetaBase, QueryReturnType, QueryThen, Expression, MaybeArray, TemplateLiteralArgs, QueryColumn, MaybePromise, FnUnknownToUnknown, RecordString, ColumnsShapeBase, ColumnsParsers, PickQueryTable, BatchParsers, HookSelect, QueryLogObject, QueryLogger, QueryDataTransform, ExpressionChain, PickQueryShape, ColumnSchemaConfig, RawSQLBase, RawSQLValues, ExpressionTypeMethod, DynamicSQLArg, ExpressionData, StaticSQLArgs, SQLQueryArgs, PickQueryTableMetaResult, EmptyTuple, PickQueryMeta, PickQueryMetaResultReturnType, QueryColumnToNullable, SelectableBase, PickQueryMetaShape, PickQueryTableMetaResultShape, PickQueryMetaResultWindows, PickOutputTypeAndOperators, PickQueryResult, ValExpression, PickOutputType, DateColumnData, ColumnToCodeCtx, Code, TimeInterval, ColumnTypeSchemaArg, ColumnDataBase, ArrayMethodsData, ForeignKeyTable, ColumnNameOfTable, BaseNumberData, PickColumnBaseData, ColumnWithDefault, StringTypeData, PrimaryKeyColumn, ParseColumn, EncodeColumn, QueryColumnsInit, QueryLogOptions, DefaultSelectColumns, DbBase, QueryCatch, TransactionState, ColumnTypeBase, PickQueryUniqueProperties, PickQueryMetaResult, IsQuery, PickQueryTableMetaResultInputType, getValueKey, PickQueryResultUniqueColumns, QueryInternalBase, PickQueryReturnType, PickType, ColumnShapeOutput, OperatorsNullable, PickQueryMetaReturnType, UniqueColumn, TimestampHelpers, Codes, ColumnDataCheckBase } from 'orchid-core';
 import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
@@ -591,6 +591,33 @@ declare class UnhandledTypeError extends OrchidOrmInternalError {
     constructor(query: Query, value: never);
 }
 
+declare const templateLiteralToSQL: (template: TemplateLiteralArgs, ctx: ToSQLCtx, quotedAs?: string) => string;
+declare class RawSQL<T extends QueryColumn, ColumnTypes = DefaultColumnTypes<ColumnSchemaConfig>> extends RawSQLBase<T, ColumnTypes> {
+    columnTypes: ColumnTypes;
+    constructor(sql: string | TemplateLiteralArgs, values?: RawSQLValues, type?: T);
+    makeSQL(ctx: ToSQLCtx, quotedAs?: string): string;
+}
+interface DynamicRawSQL<T extends QueryColumn> extends Expression<T>, ExpressionTypeMethod {
+}
+declare class DynamicRawSQL<T extends QueryColumn, ColumnTypes = DefaultColumnTypes<ColumnSchemaConfig>> extends Expression<T> {
+    fn: DynamicSQLArg<T>;
+    columnTypes: ColumnTypes;
+    result: {
+        value: T;
+    };
+    q: ExpressionData;
+    constructor(fn: DynamicSQLArg<T>);
+    makeSQL(ctx: ToSQLCtx, quotedAs?: string): string;
+}
+declare function raw<T = never>(...args: StaticSQLArgs): RawSQL<QueryColumn<T>>;
+declare function raw<T = never>(...args: [DynamicSQLArg<QueryColumn<T>>]): DynamicRawSQL<QueryColumn<T>>;
+declare const countSelect: RawSQL<QueryColumn<unknown, any>, DefaultColumnTypes<ColumnSchemaConfig<orchid_core.ColumnTypeBase<orchid_core.ColumnTypeSchemaArg, unknown, any, any, unknown, unknown, any, unknown, any, orchid_core.ColumnDataBase>>>>[];
+declare function sqlQueryArgsToExpression(args: SQLQueryArgs): RawSQL<QueryColumn>;
+interface SqlFn {
+    <T, Args extends [sql: TemplateStringsArray, ...values: unknown[]] | [sql: string] | [values: RecordUnknown, sql?: string]>(this: T, ...args: Args): Args extends [RecordUnknown] ? (...sql: TemplateLiteralArgs) => RawSQLBase<QueryColumn, T> : RawSQLBase<QueryColumn, T>;
+}
+declare const sqlFn: SqlFn;
+
 type WithSelectable<W extends WithDataItem> = keyof W['shape'] | `${W['table']}.${keyof W['shape'] & string}`;
 /**
  * The first argument of all `join` and `joinLateral` methods.
@@ -1719,11 +1746,13 @@ declare class ExpressionMethods {
      * Only for referencing a column in the query's table. For referencing joined table's columns, see [ref](#ref).
      *
      * ```ts
+     * import { sql } from './baseTable';
+     *
      * await db.table.select({
      *   // select `("table"."id" = 1 OR "table"."name" = 'name') AS "one"`,
      *   // returns a boolean
      *   one: (q) =>
-     *     q.sql<boolean>`${q.column('id')} = ${1} OR ${q.column('name')} = ${'name'}`,
+     *     sql<boolean>`${q.column('id')} = ${1} OR ${q.column('name')} = ${'name'}`,
      *
      *   // selects the same as above, but by building a query
      *   two: (q) => q.column('id').equals(1).or(q.column('name').equals('name')),
@@ -1738,11 +1767,13 @@ declare class ExpressionMethods {
      * and other dynamically defined columns.
      *
      * ```ts
+     * import { sql } from './baseTable';
+     *
      * await db.table.join('otherTable').select({
      *   // select `("otherTable"."id" = 1 OR "otherTable"."name" = 'name') AS "one"`,
      *   // returns a boolean
      *   one: (q) =>
-     *     q.sql<boolean>`${q.ref('otherTable.id')} = ${1} OR ${q.ref(
+     *     sql<boolean>`${q.ref('otherTable.id')} = ${1} OR ${q.ref(
      *       'otherTable.name',
      *     )} = ${'name'}`,
      *
@@ -1890,6 +1921,8 @@ declare class Where {
      * Constructing `WHERE` conditions:
      *
      * ```ts
+     * import { sql } from './baseTable'
+     *
      * db.table.where({
      *   // column of the current table
      *   name: 'John',
@@ -1906,8 +1939,8 @@ declare class Where {
      *   // where column equals to raw SQL
      *   // import `sql` from your `BaseTable`
      *   column: sql`sql expression`,
-     *   // or use `(q) => q.sql` for the same
-     *   column2: (q) => q.sql`sql expression`,
+     *   // or use `(q) => sql` for the same
+     *   column2: (q) => sql`sql expression`,
      *
      *   // reference other columns in such a way:
      *   firstName: (q) => q.ref('lastName'),
@@ -2667,33 +2700,6 @@ declare class JSONTextColumn<Schema extends ColumnSchemaConfig> extends ColumnTy
     toCode(ctx: ColumnToCodeCtx, key: string): Code;
 }
 
-declare const templateLiteralToSQL: (template: TemplateLiteralArgs, ctx: ToSQLCtx, quotedAs?: string) => string;
-declare class RawSQL<T extends QueryColumn, ColumnTypes = DefaultColumnTypes<ColumnSchemaConfig>> extends RawSQLBase<T, ColumnTypes> {
-    columnTypes: ColumnTypes;
-    constructor(sql: string | TemplateLiteralArgs, values?: RawSQLValues, type?: T);
-    makeSQL(ctx: ToSQLCtx, quotedAs?: string): string;
-}
-interface DynamicRawSQL<T extends QueryColumn> extends Expression<T>, ExpressionTypeMethod {
-}
-declare class DynamicRawSQL<T extends QueryColumn, ColumnTypes = DefaultColumnTypes<ColumnSchemaConfig>> extends Expression<T> {
-    fn: DynamicSQLArg<T>;
-    columnTypes: ColumnTypes;
-    result: {
-        value: T;
-    };
-    q: ExpressionData;
-    constructor(fn: DynamicSQLArg<T>);
-    makeSQL(ctx: ToSQLCtx, quotedAs?: string): string;
-}
-declare function raw<T = never>(...args: StaticSQLArgs): RawSQL<QueryColumn<T>>;
-declare function raw<T = never>(...args: [DynamicSQLArg<QueryColumn<T>>]): DynamicRawSQL<QueryColumn<T>>;
-declare const countSelect: RawSQL<QueryColumn<unknown, any>, DefaultColumnTypes<ColumnSchemaConfig<orchid_core.ColumnTypeBase<orchid_core.ColumnTypeSchemaArg, unknown, any, any, unknown, unknown, any, unknown, any, orchid_core.ColumnDataBase>>>>[];
-declare function sqlQueryArgsToExpression(args: SQLQueryArgs): RawSQL<QueryColumn>;
-interface SqlFn {
-    <T, Args extends [sql: TemplateStringsArray, ...values: unknown[]] | [sql: string] | [values: RecordUnknown, sql?: string]>(this: T, ...args: Args): Args extends [RecordUnknown] ? (...sql: TemplateLiteralArgs) => RawSQLBase<QueryColumn, T> : RawSQLBase<QueryColumn, T>;
-}
-declare const sqlFn: SqlFn;
-
 interface TableData {
     primaryKey?: TableData.PrimaryKey;
     indexes?: TableData.Index[];
@@ -3444,6 +3450,8 @@ type MapTableScopesOption<T> = T extends {
 interface DbResult<ColumnTypes> extends Db<string, never, never, never, never, never, ColumnTypes>, DbTableConstructor<ColumnTypes> {
     adapter: Adapter;
     close: Adapter['close'];
+    sql<T = unknown>(...args: StaticSQLArgs): RawSQL<QueryColumn<T>, ColumnTypes>;
+    sql<T = unknown>(...args: [DynamicSQLArg<QueryColumn<T>>]): DynamicRawSQL<QueryColumn<T>, ColumnTypes>;
 }
 /**
  * If you'd like to use the query builder of OrchidORM as a standalone tool, install `pqb` package and use `createDb` to initialize it.
@@ -4198,6 +4206,8 @@ declare class Create {
      * Each column may accept a specific value, a raw SQL, or a query that returns a single value.
      *
      * ```ts
+     * import { sql } from './baseTable';
+     *
      * const oneRecord = await db.table.create({
      *   name: 'John',
      *   password: '1234',
@@ -4209,7 +4219,7 @@ declare class Create {
      *
      * await db.table.create({
      *   // raw SQL
-     *   column1: (q) => q.sql`'John' || ' ' || 'Doe'`,
+     *   column1: () => sql`'John' || ' ' || 'Doe'`,
      *
      *   // query that returns a single value
      *   // returning multiple values will result in Postgres error
@@ -4614,7 +4624,7 @@ declare class OnConflictQueryBuilder<T extends CreateSelf, Arg extends OnConflic
      *
      * If the table has columns with **dynamic** default values, such values will be applied as well.
      *
-     * You can exclude certain columns from being merged by passing the `exclude` option.
+     * You can exclude certain columns from being merged by passing the `except` option.
      *
      * ```ts
      * // merge the full data
@@ -4904,7 +4914,9 @@ declare class Having {
      * Arguments of the aggregate function and of the comparison can be raw SQL:
      *
      * ```ts
-     * db.table.having((q) => q.count(q.sql('coalesce(one, two)')).gte(q.sql`2 + 2`));
+     * import { sql } from './baseTable';
+     *
+     * db.table.having((q) => q.count(sql('coalesce(one, two)')).gte(sql`2 + 2`));
      * ```
      *
      * @param args - raw SQL template string or one or multiple callbacks returning a boolean expression
@@ -5189,6 +5201,8 @@ declare class Select {
      * The last argument can be an object. Keys of the object are column aliases, value can be a column name, sub-query, or raw SQL expression.
      *
      * ```ts
+     * import { sql } from './baseTable'
+     *
      * // select columns of the table:
      * db.table.select('id', 'name', { idAlias: 'id' });
      *
@@ -5216,9 +5230,9 @@ declare class Select {
      *   raw: sql`1 + 2`.type((t) => t.integer()),
      * });
      *
-     * // same raw SQL query as above, but raw value is returned from a callback
+     * // same raw SQL query as above, but the sql is returned from a callback
      * db.table.select({
-     *   raw: (q) => q.sql`1 + 2`.type((t) => t.integer()),
+     *   raw: () => sql`1 + 2`.type((t) => t.integer()),
      * });
      * ```
      *
@@ -5296,7 +5310,7 @@ declare class SqlMethod<ColumnTypes> {
      *
      * ```ts
      * const subQuery = db.someTable.select({
-     *   sum: (q) => q.sql`$a + $b`.type((t) => t.decimal()).values({ a: 1, b: 2 }),
+     *   sum: () => sql`$a + $b`.type((t) => t.decimal()).values({ a: 1, b: 2 }),
      * });
      *
      * // `gt`, `gte`, `min`, `lt`, `lte`, `max` in `where`
@@ -5403,6 +5417,7 @@ declare class SqlMethod<ColumnTypes> {
      * sql`($one + $two) / $one`.type((t) => t.numeric()).values({ one: 1, two: 2 });
      * ```
      *
+     * @deprecated use `sql` exported from the `createBaseTable` (see "define a base table" in the docs)
      * @param args - template literal or an object { raw: string }
      * @return object that has `type` and `values` methods
      */
@@ -5443,77 +5458,228 @@ type WithSqlResult<T extends PickQueryWithDataColumnTypes, Name extends string,
 };
 declare class WithMethods {
     /**
-     * Add Common Table Expression (CTE) to the query.
+     * Use `with` to add a Common Table Expression (CTE) to the query.
+     *
+     * `with` can be chained to any table on `db` instance, or to `db.$queryBuilder`,
+     * note that in the latter case it won't have customized column types to use for typing SQL.
      *
      * ```ts
-     * import { columnTypes } from 'orchid-orm';
-     * import { NumberColumn } from './number';
+     * import { sql } from './baseTable';
      *
-     * // .with optionally accepts such options:
-     * type WithOptions = {
-     *   // list of columns returned by this WITH statement
-     *   // by default all columns from provided column shape will be included
-     *   // true is for default behavior
-     *   columns?: string[] | boolean;
+     * // can access custom columns when using off a table
+     * db.anyTable.with('x', (q) =>
+     *   q.select({ column: (q) => sql`123`.type((t) => t.customColumn()) }),
+     * );
      *
-     *   // Adds RECURSIVE keyword:
-     *   recursive?: true;
+     * // only default columns are available when using off `$queryBuilder`
+     * db.$queryBuilder.with('x', (q) =>
+     *   q.select({ column: (q) => sql`123`.type((t) => t.integer()) }),
+     * );
+     * ```
      *
-     *   // Adds MATERIALIZED keyword:
-     *   materialized?: true;
+     * `with` accepts query objects, callbacks returning query objects, and custom SQL expressions returned from callbacks.
      *
-     *   // Adds NOT MATERIALIZED keyword:
-     *   notMaterialized?: true;
-     * };
+     * ```ts
+     * import { sql } from './baseTable';
      *
-     * // accepts columns shape and a raw expression:
-     * db.table.with(
-     *   'alias',
-     *   {
-     *     id: columnTypes.integer(),
-     *     name: columnTypes.text(3, 100),
-     *   },
-     *   sql`SELECT id, name FROM "someTable"`,
-     * );
+     * db.table
+     *   .with(
+     *     'alias',
+     *     // define CTE by building a query
+     *     db.table.select('one', 'two', 'three').where({ x: 123 }),
+     *   )
+     *   .from('alias')
+     *   .select('one')
+     *   .where({ two: 123 });
      *
-     * // accepts query:
-     * db.table.with('alias', db.table.all());
+     * // 2nd argument can be a callback accepting a query builder
+     * db.table
+     *   .with('alias', (q) =>
+     *     // select a custom sql
+     *     q.select({ column: (q) => sql`123`.type((t) => t.integer()) }),
+     *   )
+     *   .from('alias')
+     *   .select('column')
+     *   .where({ column: 123 });
      *
-     * // accepts a callback for a query builder:
-     * db.table.with('alias', (qb) =>
-     *   qb.select({ one: sql`1`.type((t) => t.integer()) }),
-     * );
+     * // 2nd argument can be used for options
+     * db.table
+     *   .with(
+     *     'alias',
+     *     {
+     *       // all parameters are optional
+     *       materialized: true,
+     *       notMaterialized: true,
+     *     },
+     *     db.table,
+     *   )
+     *   .from('alias');
+     * ```
      *
-     * // All mentioned forms can accept options as a second argument:
-     * db.table.with(
-     *   'alias',
-     *   {
-     *     recursive: true,
-     *     materialized: true,
-     *   },
-     *   rawOrQueryOrCallback,
-     * );
+     * One `WITH` expression can reference the other:
+     *
+     * ```ts
+     * db.$queryBuilder
+     *   .with('a', db.table.select('id', 'name'))
+     *   .with('b', (q) => q.from('a').where({ key: 'value' }))
+     *   .from('b');
      * ```
      *
-     * Defined `WITH` table can be used in `.from` or `.join` with all the type safeness:
+     * Defined `WITH` expression can be used in `.from` or `.join` with all the type safeness:
      *
      * ```ts
-     * db.table.with('alias', db.table.all()).from('alias').select('alias.id');
+     * db.table.with('alias', db.table).from('alias').select('alias.id');
      *
-     * db.table
-     *   .with('alias', db.table.all())
-     *   .join('alias', 'alias.id', 'user.id')
-     *   .select('alias.id');
+     * db.firstTable
+     *   .with('secondTable', db.secondTable)
+     *   .join('secondTable', 'secondTable.someId', 'firstTable.id')
+     *   .select('firstTable.column', 'secondTable.column');
      * ```
      */
     with<T extends PickQueryMetaWithDataColumnTypes, Name extends string, Q>(this: T, name: Name, query: Q | ((q: WithQueryBuilder<T>) => Q)): WithResult<T, Name, Q extends Query ? Q : never>;
     with<T extends PickQueryMetaWithDataColumnTypes, Name extends string, Q extends Query>(this: T, name: Name, options: WithArgsOptions, query: Q | ((q: WithQueryBuilder<T>) => Q)): WithResult<T, Name, Q>;
+    /**
+     * It is priceless for fetching tree-like structures, or any other recursive cases.
+     *
+     * For example, it is useful for loading a tree of categories, where one category can include many other categories.
+     *
+     * Similarly to [with](#with), `withRecursive` can be chained to any table or `db.$queryBuilder`.
+     *
+     * For the first example, consider the employee table, an employee may or may not have a manager.
+     *
+     * ```ts
+     * class Employee extends BaseTable {
+     *   readonly table = 'employee';
+     *   columns = this.setColumns((t) => ({
+     *     id: t.identity().primaryKey(),
+     *     name: t.string(),
+     *     managerId: t.integer().nullable(),
+     *   }));
+     * }
+     * ```
+     *
+     * The task is to load all subordinates of the manager with the id 1.
+     *
+     * ```ts
+     * db.$queryBuilder
+     *   .withRecursive(
+     *     'subordinates',
+     *     // the base, anchor query: find the manager to begin recursion with
+     *     Employee.select('id', 'name', 'managerId').find(1),
+     *     // recursive query:
+     *     // find employees whos managerId is id from the surrounding subordinates CTE
+     *     (q) =>
+     *       q
+     *         .from(Employee)
+     *         .select('id', 'name', 'managerId')
+     *         .join('subordinates', 'subordinates.id', 'profile.managerId'),
+     *   )
+     *   .from('subordinates');
+     * ```
+     *
+     * As being shown, `withRecursive` accepts one query to begin with, and a second query in a callback that can reference the surrounding table expression "subordinates".
+     *
+     * These two queries are joined with `UNION ALL` by default.
+     *
+     * You can customize it by passing options after the name.
+     *
+     * ```ts
+     * db.$queryBuilder
+     *   .withRecursive(
+     *     'subordinates',
+     *     {
+     *       // all parameters are optional
+     *       union: 'UNION',
+     *       materialized: true,
+     *       notMaterialized: true,
+     *     },
+     *     // ...snip
+     *   )
+     *   .from('subordinates');
+     * ```
+     *
+     * Recursive query can be constructed with basic SQL instructions only, without referencing other tables.
+     * In the following example, we recursively select numbers from 1 to 100, and additionally apply n > 10 filter in the end.
+     *
+     * ```ts
+     * import { sql } from './baseTable';
+     *
+     * db.$queryBuilder
+     *   .withRecursive(
+     *     't',
+     *     // select `1 AS n` for the base query
+     *     (q) => q.select({ n: (q) => sql`1`.type((t) => t.integer()) }),
+     *     // select `n + 1 AS n` for the recursive part
+     *     (q) =>
+     *       q
+     *         .from('t')
+     *         // type can be omitted here because it was defined in the base query
+     *         .select({ n: (q) => sql`n + 1` })
+     *         .where({ n: { lt: 100 } }),
+     *   )
+     *   .from('t')
+     *   .where({ n: { gt: 10 } });
+     * ```
+     */
     withRecursive<T extends PickQueryMetaWithDataColumnTypes, Name extends string, Q extends Query, Result = WithResult<T, Name, Q>>(this: T, name: Name, base: Q | ((qb: WithQueryBuilder<T>) => Q), recursive: (qb: {
         [K in keyof Result]: K extends 'result' ? Q['result'] : Result[K];
     }) => Query): Result;
     withRecursive<T extends PickQueryMetaWithDataColumnTypes, Name extends string, Q extends Query, Result = WithResult<T, Name, Q>>(this: T, name: Name, options: WithRecursiveOptions, base: Q | ((qb: WithQueryBuilder<T>) => Q), recursive: (qb: {
         [K in keyof Result]: K extends 'result' ? Q['result'] : Result[K];
     }) => Query): Result;
+    /**
+     * Use `withSql` to add a Common Table Expression (CTE) based on a custom SQL.
+     *
+     * Similarly to [with](#with), `withRecursive` can be chained to any table or `db.$queryBuilder`.
+     *
+     * ```ts
+     * import { sql } from './baseTable';
+     *
+     * db.table
+     *   .withSql(
+     *     'alias',
+     *     // define column types of the expression:
+     *     (t) => ({
+     *       one: t.integer(),
+     *       two: t.string(),
+     *     }),
+     *     // define SQL expression:
+     *     (q) => sql`(VALUES (1, 'two')) t(one, two)`,
+     *   )
+     *   // is not prefixed in the middle of a query chain
+     *   .withSql(
+     *     'second',
+     *     (t) => ({
+     *       x: t.integer(),
+     *     }),
+     *     (q) => sql`(VALUES (1)) t(x)`,
+     *   )
+     *   .from('alias');
+     * ```
+     *
+     * Options can be passed via a second argument:
+     *
+     * ```ts
+     * import { sql } from './baseTable';
+     *
+     * db.table
+     *   .withSql(
+     *     'alias',
+     *     {
+     *       // all parameters are optional
+     *       recursive: true,
+     *       materialized: true,
+     *       notMaterialized: true,
+     *     },
+     *     (t) => ({
+     *       one: t.integer(),
+     *       two: t.string(),
+     *     }),
+     *     (q) => sql`(VALUES (1, 'two')) t(one, two)`,
+     *   )
+     *   .from('alias');
+     * ```
+     */
     withSql<T extends PickQueryWithDataColumnTypes, Name extends string, Shape extends ColumnsShapeBase>(this: T, name: Name, options: WithOptions, shape: (t: T['columnTypes']) => Shape, expr: (q: T) => Expression): WithSqlResult<T, Name, Shape>;
     withSql<T extends PickQueryWithDataColumnTypes, Name extends string, Shape extends ColumnsShapeBase>(this: T, name: Name, shape: (t: T['columnTypes']) => Shape, expr: (q: T) => Expression): WithSqlResult<T, Name, Shape>;
 }
@@ -5531,13 +5697,15 @@ declare class Union {
      * Creates a union query, takes one or more queries or SQL expressions.
      *
      * ```ts
+     * import { sql } from './baseTable';
+     *
      * // The first query of the union
      * db.one
      *   .select('id', 'name')
      *   // add two more queries to the union
      *   .union(
      *     db.two.select('id', 'name'),
-     *     (q = q.sql`SELECT id, name FROM "thirdTable"`),
+     *     (q = sql`SELECT id, name FROM "thirdTable"`),
      *   )
      *   // sub-sequent `union` is equivalent to passing multiple queries into a single `union`
      *   .union(db.three.select('id', 'name'));
@@ -5674,6 +5842,8 @@ declare class Update {
      * and [jsonRemove](/guide/advanced-queries.html#jsonremove) for a JSON column (see `jsonColumn` below).
      *
      * ```ts
+     * import { sql } from './baseTable';
+     *
      * // returns number of updated records by default
      * const updatedCount = await db.table
      *   .where({ name: 'old name' })
@@ -5699,7 +5869,7 @@ declare class Update {
      *   column1: 123,
      *
      *   // use raw SQL to update the column
-     *   column2: (q) => q.sql`2 + 2`,
+     *   column2: () => sql`2 + 2`,
      *
      *   // use query that returns a single value
      *   // returning multiple values will result in Postgres error

package/dist/index.js

@@ -7387,6 +7387,8 @@ class Create {
    * Each column may accept a specific value, a raw SQL, or a query that returns a single value.
    *
    * ```ts
+   * import { sql } from './baseTable';
+   *
    * const oneRecord = await db.table.create({
    *   name: 'John',
    *   password: '1234',
@@ -7398,7 +7400,7 @@ class Create {
    *
    * await db.table.create({
    *   // raw SQL
-   *   column1: (q) => q.sql`'John' || ' ' || 'Doe'`,
+   *   column1: () => sql`'John' || ' ' || 'Doe'`,
    *
    *   // query that returns a single value
    *   // returning multiple values will result in Postgres error
@@ -7872,7 +7874,7 @@ class OnConflictQueryBuilder {
    *
    * If the table has columns with **dynamic** default values, such values will be applied as well.
    *
-   * You can exclude certain columns from being merged by passing the `exclude` option.
+   * You can exclude certain columns from being merged by passing the `except` option.
    *
    * ```ts
    * // merge the full data
@@ -8113,7 +8115,9 @@ class Having {
    * Arguments of the aggregate function and of the comparison can be raw SQL:
    *
    * ```ts
-   * db.table.having((q) => q.count(q.sql('coalesce(one, two)')).gte(q.sql`2 + 2`));
+   * import { sql } from './baseTable';
+   *
+   * db.table.having((q) => q.count(sql('coalesce(one, two)')).gte(sql`2 + 2`));
    * ```
    *
    * @param args - raw SQL template string or one or multiple callbacks returning a boolean expression
@@ -9211,13 +9215,15 @@ class Union {
    * Creates a union query, takes one or more queries or SQL expressions.
    *
    * ```ts
+   * import { sql } from './baseTable';
+   *
    * // The first query of the union
    * db.one
    *   .select('id', 'name')
    *   // add two more queries to the union
    *   .union(
    *     db.two.select('id', 'name'),
-   *     (q = q.sql`SELECT id, name FROM "thirdTable"`),
+   *     (q = sql`SELECT id, name FROM "thirdTable"`),
    *   )
    *   // sub-sequent `union` is equivalent to passing multiple queries into a single `union`
    *   .union(db.three.select('id', 'name'));
@@ -9526,6 +9532,8 @@ class Where {
    * Constructing `WHERE` conditions:
    *
    * ```ts
+   * import { sql } from './baseTable'
+   *
    * db.table.where({
    *   // column of the current table
    *   name: 'John',
@@ -9542,8 +9550,8 @@ class Where {
    *   // where column equals to raw SQL
    *   // import `sql` from your `BaseTable`
    *   column: sql`sql expression`,
-   *   // or use `(q) => q.sql` for the same
-   *   column2: (q) => q.sql`sql expression`,
+   *   // or use `(q) => sql` for the same
+   *   column2: (q) => sql`sql expression`,
    *
    *   // reference other columns in such a way:
    *   firstName: (q) => q.ref('lastName'),
@@ -10368,6 +10376,8 @@ class Update {
    * and [jsonRemove](/guide/advanced-queries.html#jsonremove) for a JSON column (see `jsonColumn` below).
    *
    * ```ts
+   * import { sql } from './baseTable';
+   *
    * // returns number of updated records by default
    * const updatedCount = await db.table
    *   .where({ name: 'old name' })
@@ -10393,7 +10403,7 @@ class Update {
    *   column1: 123,
    *
    *   // use raw SQL to update the column
-   *   column2: (q) => q.sql`2 + 2`,
+   *   column2: () => sql`2 + 2`,
    *
    *   // use query that returns a single value
    *   // returning multiple values will result in Postgres error
@@ -11405,11 +11415,13 @@ class ExpressionMethods {
    * Only for referencing a column in the query's table. For referencing joined table's columns, see [ref](#ref).
    *
    * ```ts
+   * import { sql } from './baseTable';
+   *
    * await db.table.select({
    *   // select `("table"."id" = 1 OR "table"."name" = 'name') AS "one"`,
    *   // returns a boolean
    *   one: (q) =>
-   *     q.sql<boolean>`${q.column('id')} = ${1} OR ${q.column('name')} = ${'name'}`,
+   *     sql<boolean>`${q.column('id')} = ${1} OR ${q.column('name')} = ${'name'}`,
    *
    *   // selects the same as above, but by building a query
    *   two: (q) => q.column('id').equals(1).or(q.column('name').equals('name')),
@@ -11430,11 +11442,13 @@ class ExpressionMethods {
    * and other dynamically defined columns.
    *
    * ```ts
+   * import { sql } from './baseTable';
+   *
    * await db.table.join('otherTable').select({
    *   // select `("otherTable"."id" = 1 OR "otherTable"."name" = 'name') AS "one"`,
    *   // returns a boolean
    *   one: (q) =>
-   *     q.sql<boolean>`${q.ref('otherTable.id')} = ${1} OR ${q.ref(
+   *     sql<boolean>`${q.ref('otherTable.id')} = ${1} OR ${q.ref(
    *       'otherTable.name',
    *     )} = ${'name'}`,
    *
@@ -12657,6 +12671,11 @@ const createDb = (_a) => {
   for (const name of Object.getOwnPropertyNames(Db.prototype)) {
     db[name] = Db.prototype[name];
   }
+  db.sql = (...args) => {
+    const sql = raw(...args);
+    sql.columnTypes = ct;
+    return sql;
+  };
   return db;
 };
 const _initQueryBuilder = (adapter, columnTypes, transactionStorage, commonOptions, options) => {