kysely 0.7.8 → 0.9.0

package/dist/esm/dialect/postgres/postgres-driver.js

@@ -37,18 +37,18 @@ export class PostgresDriver {
         if (settings.isolationLevel) {
             await connection.executeQuery({
                 sql: `start transaction isolation level ${settings.isolationLevel}`,
-                bindings: [],
+                parameters: [],
             });
         }
         else {
-            await connection.executeQuery({ sql: 'begin', bindings: [] });
+            await connection.executeQuery({ sql: 'begin', parameters: [] });
         }
     }
     async commitTransaction(connection) {
-        await connection.executeQuery({ sql: 'commit', bindings: [] });
+        await connection.executeQuery({ sql: 'commit', parameters: [] });
     }
     async rollbackTransaction(connection) {
-        await connection.executeQuery({ sql: 'rollback', bindings: [] });
+        await connection.executeQuery({ sql: 'rollback', parameters: [] });
     }
     async releaseConnection(connection) {
         const pgConnection = connection;
@@ -86,7 +86,7 @@ class PostgresConnection {
     }
     async executeQuery(compiledQuery) {
         const result = await this.#client.query(compiledQuery.sql, [
-            ...compiledQuery.bindings,
+            ...compiledQuery.parameters,
         ]);
         if (result.command === 'UPDATE' || result.command === 'DELETE') {
             return {

package/dist/esm/operation-node/primitive-value-list-node.js

@@ -9,7 +9,7 @@ export const PrimitiveValueListNode = freeze({
     create(values) {
         return freeze({
             kind: 'PrimitiveValueListNode',
-            values: freeze(values),
+            values: freeze([...values]),
         });
     },
 });

package/dist/esm/parser/insert-values-parser.d.ts

@@ -9,7 +9,7 @@ export declare type InsertObject<DB, TB extends keyof DB> = {
     [C in keyof DB[TB]]: InsertValueExpression<DB[TB][C]>;
 };
 export declare type InsertObjectOrList<DB, TB extends keyof DB> = InsertObject<DB, TB> | InsertObject<DB, TB>[];
-declare type InsertValueExpression<T extends PrimitiveValue> = T | AnyQueryBuilder | AnyRawBuilder | GeneratedPlaceholder;
+declare type InsertValueExpression<T> = T | AnyQueryBuilder | AnyRawBuilder | GeneratedPlaceholder;
 export declare function parseInsertObjectOrList(args: InsertObjectOrList<any, any>): [ReadonlyArray<ColumnNode>, ReadonlyArray<InsertValuesNode>];
 export declare function parseInsertValueExpression(value: InsertValueExpression<PrimitiveValue>): ValueNode | RawNode | SelectQueryNode;
 export {};

package/dist/esm/parser/join-parser.d.ts

@@ -1,8 +1,11 @@
 import { JoinNode, JoinType } from '../operation-node/join-node.js';
 import { AnyColumn, AnyColumnWithTable } from '../util/type-utils.js';
-import { ExtractAliasFromTableExpression, TableExpressionDatabaseType } from './table-parser.js';
+import { ExtractAliasFromTableExpression, TableExpressionDatabase } from './table-parser.js';
 import { JoinBuilder } from '../query-builder/join-builder.js';
 import { ParseContext } from './parse-context.js';
-export declare type JoinReferenceExpression<DB, TB extends keyof DB, F> = AnyColumn<TableExpressionDatabaseType<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>> | AnyColumnWithTable<TableExpressionDatabaseType<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
-export declare type JoinCallbackExpression<DB, TB extends keyof DB, F> = (join: JoinBuilder<TableExpressionDatabaseType<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>) => JoinBuilder<any, any>;
+export declare type JoinReferenceExpression<DB, TB extends keyof DB, F> = AnyJoinColumn<DB, TB, F> | AnyJoinColumnWithTable<DB, TB, F>;
+export declare type JoinCallbackExpression<DB, TB extends keyof DB, F> = (join: JoinBuilder<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>) => JoinBuilder<any, any>;
+declare type AnyJoinColumn<DB, TB extends keyof DB, F> = AnyColumn<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
+declare type AnyJoinColumnWithTable<DB, TB extends keyof DB, F> = AnyColumnWithTable<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
 export declare function parseJoin(ctx: ParseContext, joinType: JoinType, args: any[]): JoinNode;
+export {};

package/dist/esm/parser/table-parser.d.ts

@@ -1,21 +1,32 @@
 import { AliasedQueryBuilder, QueryBuilder } from '../query-builder/query-builder.js';
 import { TableNode } from '../operation-node/table-node.js';
-import { AliasedQueryBuilderFactory, AnyAliasedQueryBuilder, AnyAliasedRawBuilder } from '../util/type-utils.js';
+import { AliasedQueryBuilderFactory, AnyAliasedQueryBuilder, AnyAliasedRawBuilder, Nullable } from '../util/type-utils.js';
 import { AliasedRawBuilder } from '../raw-builder/raw-builder.js';
 import { TableExpressionNode } from '../operation-node/operation-node-utils.js';
 import { ParseContext } from './parse-context.js';
 export declare type TableExpression<DB, TB extends keyof DB> = TableReference<DB> | AnyAliasedQueryBuilder | AliasedQueryBuilderFactory<DB, TB>;
 export declare type TableExpressionOrList<DB, TB extends keyof DB> = TableExpression<DB, TB> | ReadonlyArray<TableExpression<DB, TB>>;
 export declare type TableReference<DB> = AnyAliasedTable<DB, any, any> | AnyTable<DB> | AnyAliasedRawBuilder;
-export declare type QueryBuilderWithTable<DB, TB extends keyof DB, O, TE> = QueryBuilder<TableExpressionDatabaseType<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
-export declare type TableExpressionDatabaseType<DB, TE> = DB extends ExtractDatabaseTypeFromTableExpression<DB, TE> ? DB : DB & ExtractDatabaseTypeFromTableExpression<DB, TE>;
+export declare type QueryBuilderWithTable<DB, TB extends keyof DB, O, TE> = QueryBuilder<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type TableExpressionDatabase<DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
+    [C in keyof DB | A]: C extends A ? ExtractRowTypeFromTableExpression<DB, TE, C> : C extends keyof DB ? DB[C] : never;
+};
+export declare type QueryBuilderWithLeftJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<LeftJoinTableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type LeftJoinTableExpressionDatabase<DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
+    [C in keyof DB | A]: C extends A ? Nullable<ExtractRowTypeFromTableExpression<DB, TE, C>> : C extends keyof DB ? DB[C] : never;
+};
+export declare type QueryBuilderWithRightJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<RightJoinTableExpressionDatabase<DB, TB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type RightJoinTableExpressionDatabase<DB, TB extends keyof DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
+    [C in keyof DB | A]: C extends A ? ExtractRowTypeFromTableExpression<DB, TE, C> : C extends keyof DB ? C extends TB ? Nullable<DB[C]> : DB[C] : never;
+};
+export declare type QueryBuilderWithFullJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<FullJoinTableExpressionDatabase<DB, TB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type FullJoinTableExpressionDatabase<DB, TB extends keyof DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
+    [C in keyof DB | A]: C extends A ? Nullable<ExtractRowTypeFromTableExpression<DB, TE, C>> : C extends keyof DB ? C extends TB ? Nullable<DB[C]> : DB[C] : never;
+};
 export declare type ExtractAliasFromTableExpression<DB, TE> = TE extends `${string} as ${infer TA}` ? TA : TE extends keyof DB ? TE : TE extends AliasedQueryBuilder<any, any, any, infer QA> ? QA : TE extends (qb: any) => AliasedQueryBuilder<any, any, any, infer QA> ? QA : TE extends AliasedRawBuilder<any, infer RA> ? RA : TE extends (qb: any) => AliasedRawBuilder<any, infer RA> ? RA : never;
+declare type ExtractRowTypeFromTableExpression<DB, TE, A extends keyof any> = TE extends `${infer T} as ${infer TA}` ? TA extends A ? T extends keyof DB ? DB[T] : never : never : TE extends A ? TE extends keyof DB ? DB[TE] : never : TE extends AliasedQueryBuilder<any, any, infer O, infer QA> ? QA extends A ? O : never : TE extends (qb: any) => AliasedQueryBuilder<any, any, infer O, infer QA> ? QA extends A ? O : never : TE extends AliasedRawBuilder<infer O, infer RA> ? RA extends A ? O : never : never;
 declare type AnyAliasedTable<DB, TB extends keyof DB, A extends string> = TB extends string ? `${TB} as ${A}` : never;
 declare type AnyTable<DB> = keyof DB;
-declare type ExtractDatabaseTypeFromTableExpression<DB, TE> = {
-    [A in ExtractAliasFromTableExpression<DB, TE>]: ExtractRowTypeFromTableExpression<DB, TE, A>;
-};
-declare type ExtractRowTypeFromTableExpression<DB, TE, A extends keyof any> = TE extends `${infer T} as ${infer TA}` ? TA extends A ? T extends keyof DB ? DB[T] : never : never : TE extends A ? TE extends keyof DB ? DB[TE] : never : TE extends AliasedQueryBuilder<any, any, infer O, infer QA> ? QA extends A ? O : never : TE extends (qb: any) => AliasedQueryBuilder<any, any, infer O, infer QA> ? QA extends A ? O : never : TE extends AliasedRawBuilder<infer O, infer RA> ? RA extends A ? O : never : never;
 export declare function parseTableExpressionOrList(ctx: ParseContext, table: TableExpressionOrList<any, any>): TableExpressionNode[];
 export declare function parseTableExpression(ctx: ParseContext, table: TableExpression<any, any>): TableExpressionNode;
 export declare function parseAliasedTable(from: string): TableExpressionNode;

package/dist/esm/parser/update-set-parser.d.ts

@@ -8,6 +8,6 @@ import { ParseContext } from './parse-context.js';
 export declare type MutationObject<DB, TB extends keyof DB> = {
     [C in keyof DB[TB]]?: MutationValueExpression<DB, TB, DB[TB][C]>;
 };
-export declare type MutationValueExpression<DB, TB extends keyof DB, T extends PrimitiveValue> = T | AnyQueryBuilder | QueryBuilderFactory<DB, TB> | AnyRawBuilder | RawBuilderFactory<DB, TB>;
+export declare type MutationValueExpression<DB, TB extends keyof DB, T> = T | AnyQueryBuilder | QueryBuilderFactory<DB, TB> | AnyRawBuilder | RawBuilderFactory<DB, TB>;
 export declare function parseUpdateObject(ctx: ParseContext, row: MutationObject<any, any>): ReadonlyArray<ColumnUpdateNode>;
 export declare function parseMutationValueExpression(ctx: ParseContext, value: MutationValueExpression<any, any, PrimitiveValue>): ValueNode | RawNode | SelectQueryNode;

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

@@ -66,9 +66,9 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * Calls the `sum` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
+     * will be `number | string | BigInt` by default. This is because Kysely can't
+     * know the type the db driver outputs. Sometimes the output can be larger than
+     * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
      * know if you've done so.
      *
@@ -88,9 +88,9 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * Calls the `count` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
+     * will be `number | string | BigInt` by default. This is because Kysely can't
+     * know the type the db driver outputs. Sometimes the output can be larger than
+     * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
      * know if you've done so.
      *

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

@@ -79,9 +79,9 @@ export class FunctionBuilder {
      * Calls the `sum` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
+     * will be `number | string | BigInt` by default. This is because Kysely can't
+     * know the type the db driver outputs. Sometimes the output can be larger than
+     * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
      * know if you've done so.
      *
@@ -103,9 +103,9 @@ export class FunctionBuilder {
      * Calls the `count` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
+     * will be `number | string | BigInt` by default. This is because Kysely can't
+     * know the type the db driver outputs. Sometimes the output can be larger than
+     * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
      * know if you've done so.
      *
@@ -128,7 +128,7 @@ export class FunctionBuilder {
             queryId: createQueryId(),
             executor: this.#props.executor,
             sql: `${fn}(??)`,
-            params: [column],
+            parameters: [column],
         });
     }
 }

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

@@ -2,7 +2,7 @@ import { AliasNode } from '../operation-node/alias-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
-import { TableExpression, QueryBuilderWithTable } from '../parser/table-parser.js';
+import { TableExpression, QueryBuilderWithTable, QueryBuilderWithLeftJoin, QueryBuilderWithRightJoin, QueryBuilderWithFullJoin } from '../parser/table-parser.js';
 import { SelectExpression, QueryBuilderWithSelection, SelectAllQueryBuilder } from '../parser/select-parser.js';
 import { ExistsExpression, FilterOperator } from '../parser/filter-parser.js';
 import { InsertObject } from '../parser/insert-values-parser.js';
@@ -869,20 +869,20 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a left join
      * instead of an inner join.
      */
-    leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithLeftJoin<DB, TB, O, TE>;
+    leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithLeftJoin<DB, TB, O, TE>;
     /**
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a right join
      * instead of an inner join.
      */
-    rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithRightJoin<DB, TB, O, TE>;
+    rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithRightJoin<DB, TB, O, TE>;
     /**
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a full join
      * instead of an inner join.
      */
-    fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithFullJoin<DB, TB, O, TE>;
+    fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithFullJoin<DB, TB, O, TE>;
     /**
      * Sets the values to insert for an {@link Kysely.insertInto | insert} query.
      *

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

@@ -1,4 +1,4 @@
 export interface CompiledQuery {
     readonly sql: string;
-    readonly bindings: ReadonlyArray<any>;
+    readonly parameters: ReadonlyArray<any>;
 }

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

@@ -62,7 +62,7 @@ import { ModifyColumnNode } from '../operation-node/modify-column-node.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
-    protected get numBindings(): number;
+    protected get numParameters(): number;
     compileQuery(node: RootOperationNode): CompiledQuery;
     protected getSql(): string;
     protected visitSelectQuery(node: SelectQueryNode): void;
@@ -92,6 +92,7 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitTable(node: TableNode): void;
     protected visitCreateTable(node: CreateTableNode): void;
     protected visitColumnDefinition(node: ColumnDefinitionNode): void;
+    protected getAutoIncrement(): string;
     protected visitReferences(node: ReferencesNode): void;
     protected visitDropTable(node: DropTableNode): void;
     protected visitDataType(node: DataTypeNode): void;
@@ -129,6 +130,6 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected getLeftIdentifierWrapper(): string;
     protected getRightIdentifierWrapper(): string;
     protected getCurrentParameterPlaceholder(): string;
-    protected addBinding(binding: any): void;
+    protected addParameter(parameter: any): void;
     protected appendImmediateValue(value: PrimitiveValue): void;
 }

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

@@ -1,25 +1,24 @@
-import { DataTypeNode } from '../operation-node/data-type-node.js';
 import { OperationNodeVisitor } from '../operation-node/operation-node-visitor.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { RawNode } from '../operation-node/raw-node.js';
 import { getLast, freeze, isString, isNumber, isBoolean, isNull, isDate, isBigInt, } from '../util/object-utils.js';
 export class DefaultQueryCompiler extends OperationNodeVisitor {
-    #sqlFragments = [];
-    #bindings = [];
-    get numBindings() {
-        return this.#bindings.length;
+    #sql = '';
+    #parameters = [];
+    get numParameters() {
+        return this.#parameters.length;
     }
     compileQuery(node) {
-        this.#sqlFragments = [];
-        this.#bindings = [];
+        this.#sql = '';
+        this.#parameters = [];
         this.visitNode(node);
         return freeze({
             sql: this.getSql(),
-            bindings: this.#bindings,
+            parameters: this.#parameters,
         });
     }
     getSql() {
-        return this.#sqlFragments.join('');
+        return this.#sql;
     }
     visitSelectQuery(node) {
         // This is a sub query if this is not the root node.
@@ -289,19 +288,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     visitColumnDefinition(node) {
         this.visitNode(node.column);
         this.append(' ');
-        if (node.isAutoIncrementing) {
-            // Postgres overrides the data type for autoincrementing columns.
-            if (DataTypeNode.is(node.dataType) &&
-                node.dataType.dataType === 'bigint') {
-                this.append('bigserial');
-            }
-            else {
-                this.append('serial');
-            }
-        }
-        else {
-            this.visitNode(node.dataType);
-        }
+        this.visitNode(node.dataType);
         if (node.defaultTo) {
             this.append(' default ');
             this.visitNode(node.defaultTo);
@@ -309,6 +296,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         if (!node.isNullable) {
             this.append(' not null');
         }
+        if (node.isAutoIncrementing) {
+            this.append(' ');
+            this.append(this.getAutoIncrement());
+        }
         if (node.isUnique) {
             this.append(' unique');
         }
@@ -324,6 +315,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.visitNode(node.check);
         }
     }
+    getAutoIncrement() {
+        return 'auto_increment';
+    }
     visitReferences(node) {
         this.append('references ');
         this.visitNode(node.table);
@@ -634,10 +628,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.visitNode(node.constraintName);
     }
     append(str) {
-        this.#sqlFragments.push(str);
+        this.#sql += str;
     }
     appendValue(value) {
-        this.addBinding(value);
+        this.addParameter(value);
         this.append(this.getCurrentParameterPlaceholder());
     }
     getLeftIdentifierWrapper() {
@@ -647,10 +641,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         return '"';
     }
     getCurrentParameterPlaceholder() {
-        return '$' + this.numBindings;
+        return '$' + this.numParameters;
     }
-    addBinding(binding) {
-        this.#bindings.push(binding);
+    addParameter(parameter) {
+        this.#parameters.push(parameter);
     }
     appendImmediateValue(value) {
         if (isString(value)) {

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

@@ -10,7 +10,7 @@ export declare class QueryCreator<DB> {
     #private;
     constructor(props: QueryCreatorProps);
     /**
-     * Creates a `select` query builder against the given table/tables.
+     * Creates a `select` query builder for the given table or tables.
      *
      * The tables passed to this method are built as the query's `from` clause.
      *
@@ -221,6 +221,9 @@ export declare class QueryCreator<DB> {
      * Sets the schema to be used for all table references that don't explicitly
      * specify a schema.
      *
+     * This only affects the query created through the builder returned from
+     * this method and doesn't modify the `db` instance.
+     *
      * @example
      * ```
      * await db.withSchema('mammals')
@@ -261,10 +264,10 @@ export declare class QueryCreator<DB> {
      * Provides a way to pass arbitrary SQL into your query and executing completely
      * raw queries.
      *
-     * You can use strings `?` and `??` in the `sql` to bind parameters such as
+     * You can use the strings `?` and `??` in the `sql` to bind parameters such as
      * user input to the SQL. You should never EVER concatenate untrusted user
      * input to the SQL string to avoid injection vulnerabilities. Instead use `?`
-     * in place of the value and pass the actual value in the `params` list. See
+     * in place of a value and pass the actual value in the `parameters` list. See
      * the examples below.
      *
      * You should only use `raw` when there is no other way to get the job done. This is
@@ -276,11 +279,11 @@ export declare class QueryCreator<DB> {
      * Raw builder instances can be passed to pretty much anywhere: `select`, `where`,
      * `*Join`, `groupBy`, `orderBy` etc. Just try it. If the method accepts it, it works.
      *
-     * @param sql - The raw SQL. Special strings `?` and `??` can be used to provide
-     *    parameter bindings. `?` for values and `??` for identifiers such as column names
+     * @param sql - The raw SQL. Special strings `?` and `??` can be used as parameter
+     *    placeholders. `?` for values and `??` for identifiers such as column names
      *    or `column.table` references.
      *
-     * @param params - The parameters that will be bound to the `?` and `??` bindings in
+     * @param params - The parameters that will be bound to the `?` and `??` placeholders in
      *    the sql string.
      *
      * @example
@@ -318,7 +321,7 @@ export declare class QueryCreator<DB> {
      *     the output type. In this case you need to use the `castTo` method on the query
      *     to specify a return type for the query.
      *
-     * We could've also used `??` bindings to provide `first_name` and `last_name` like
+     * We could've also used a `??` placeholder to provide `first_name` and `last_name` like
      * this:
      *
      * ```ts
@@ -333,9 +336,9 @@ export declare class QueryCreator<DB> {
      *
      * But it's often cleaner to just write the column names in the SQL. Again remember to
      * never concatenate column names or any other untrusted user input to the SQL string or you
-     * are going to create an injection vulnerability. All user input should go to the bindings
+     * are going to create an injection vulnerability. All user input should go to the parameters
      * array, never to the SQL string directly. But if the column names or values are trusted
-     * and known at compile time, there is no reason to use bindings.
+     * and known at compile time, there is no reason to use parameters.
      *
      * @example
      * Example of using `raw` in `where`:
@@ -361,7 +364,7 @@ export declare class QueryCreator<DB> {
      *
      * The function in the above example returns people that are older than the given number of
      * years. The number of years in this example is an untrusted user input, and therefore we use
-     * a `?` binding for it.
+     * a `?` placeholder for it.
      *
      * @example
      * Example of creating a completely raw query from scratch:
@@ -375,7 +378,7 @@ export declare class QueryCreator<DB> {
      * The result of `execute()` method is always an array. In this case the type of
      * the `persons` variable is `Person[]`.
      */
-    raw<T = unknown>(sql: string, params?: any[]): RawBuilder<T>;
+    raw<T = unknown>(sql: string, parameters?: any[]): RawBuilder<T>;
 }
 export interface QueryCreatorProps {
     readonly executor: QueryExecutor;

package/dist/esm/query-creator.js

@@ -155,6 +155,9 @@ export class QueryCreator {
      * Sets the schema to be used for all table references that don't explicitly
      * specify a schema.
      *
+     * This only affects the query created through the builder returned from
+     * this method and doesn't modify the `db` instance.
+     *
      * @example
      * ```
      * await db.withSchema('mammals')
@@ -200,10 +203,10 @@ export class QueryCreator {
      * Provides a way to pass arbitrary SQL into your query and executing completely
      * raw queries.
      *
-     * You can use strings `?` and `??` in the `sql` to bind parameters such as
+     * You can use the strings `?` and `??` in the `sql` to bind parameters such as
      * user input to the SQL. You should never EVER concatenate untrusted user
      * input to the SQL string to avoid injection vulnerabilities. Instead use `?`
-     * in place of the value and pass the actual value in the `params` list. See
+     * in place of a value and pass the actual value in the `parameters` list. See
      * the examples below.
      *
      * You should only use `raw` when there is no other way to get the job done. This is
@@ -215,11 +218,11 @@ export class QueryCreator {
      * Raw builder instances can be passed to pretty much anywhere: `select`, `where`,
      * `*Join`, `groupBy`, `orderBy` etc. Just try it. If the method accepts it, it works.
      *
-     * @param sql - The raw SQL. Special strings `?` and `??` can be used to provide
-     *    parameter bindings. `?` for values and `??` for identifiers such as column names
+     * @param sql - The raw SQL. Special strings `?` and `??` can be used as parameter
+     *    placeholders. `?` for values and `??` for identifiers such as column names
      *    or `column.table` references.
      *
-     * @param params - The parameters that will be bound to the `?` and `??` bindings in
+     * @param params - The parameters that will be bound to the `?` and `??` placeholders in
      *    the sql string.
      *
      * @example
@@ -257,7 +260,7 @@ export class QueryCreator {
      *     the output type. In this case you need to use the `castTo` method on the query
      *     to specify a return type for the query.
      *
-     * We could've also used `??` bindings to provide `first_name` and `last_name` like
+     * We could've also used a `??` placeholder to provide `first_name` and `last_name` like
      * this:
      *
      * ```ts
@@ -272,9 +275,9 @@ export class QueryCreator {
      *
      * But it's often cleaner to just write the column names in the SQL. Again remember to
      * never concatenate column names or any other untrusted user input to the SQL string or you
-     * are going to create an injection vulnerability. All user input should go to the bindings
+     * are going to create an injection vulnerability. All user input should go to the parameters
      * array, never to the SQL string directly. But if the column names or values are trusted
-     * and known at compile time, there is no reason to use bindings.
+     * and known at compile time, there is no reason to use parameters.
      *
      * @example
      * Example of using `raw` in `where`:
@@ -300,7 +303,7 @@ export class QueryCreator {
      *
      * The function in the above example returns people that are older than the given number of
      * years. The number of years in this example is an untrusted user input, and therefore we use
-     * a `?` binding for it.
+     * a `?` placeholder for it.
      *
      * @example
      * Example of creating a completely raw query from scratch:
@@ -314,12 +317,12 @@ export class QueryCreator {
      * The result of `execute()` method is always an array. In this case the type of
      * the `persons` variable is `Person[]`.
      */
-    raw(sql, params) {
+    raw(sql, parameters) {
         return new RawBuilder({
             queryId: createQueryId(),
             executor: this.#props.executor,
             sql,
-            params,
+            parameters,
         });
     }
 }

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

@@ -41,5 +41,5 @@ export interface RawBuilderProps {
     readonly queryId: QueryId;
     readonly executor: QueryExecutor;
     readonly sql: string;
-    readonly params?: any;
+    readonly parameters?: any;
 }

package/dist/esm/raw-builder/raw-builder.js

@@ -25,24 +25,24 @@ export class RawBuilder {
         });
     }
     toOperationNode() {
-        const bindingRegex = /(\?\??)/g;
+        const parameterPlaceholderRegex = /(\?\??)/g;
         const sql = this.#props.sql;
-        const params = this.#props.params ?? [];
+        const parameters = this.#props.parameters ?? [];
         const sqlFragments = [];
         const argNodes = [];
         let paramIdx = 0;
         let sqlIdx = 0;
         let match = null;
-        while ((match = bindingRegex.exec(sql))) {
+        while ((match = parameterPlaceholderRegex.exec(sql))) {
             const str = match[1];
-            if (paramIdx >= params.length) {
-                throw new Error(`value not provided for all bindings in string ${sql}`);
+            if (paramIdx >= parameters.length) {
+                throw new Error(`value not provided for all placeholders in string ${sql}`);
             }
             if (match.index > 0 && sql[match.index - 1] === '\\') {
                 continue;
             }
             sqlFragments.push(sql.slice(sqlIdx, match.index).replaceAll('\\?', '?'));
-            argNodes.push(parseRawArg(str, params[paramIdx]));
+            argNodes.push(parseRawArg(str, parameters[paramIdx]));
             sqlIdx = match.index + str.length;
             ++paramIdx;
         }

package/dist/esm/schema/alter-table-builder.d.ts

@@ -12,6 +12,9 @@ import { QueryId } from '../util/query-id.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { DataTypeExpression } from '../parser/data-type-parser.js';
 import { ForeignKeyConstraintBuilder, ForeignKeyConstraintBuilderInterface } from './foreign-key-constraint-builder.js';
+/**
+ * This builder can be used to create a `alter table` query.
+ */
 export declare class AlterTableBuilder {
     #private;
     constructor(props: AlterTableBuilderProps);

package/dist/esm/schema/alter-table-builder.js

@@ -20,6 +20,9 @@ import { UniqueConstraintNode } from '../operation-node/unique-constraint-node.j
 import { CheckConstraintNode } from '../operation-node/check-constraint-node.js';
 import { ForeignKeyConstraintNode } from '../operation-node/foreign-key-constraint-node.js';
 import { ColumnNode } from '../operation-node/column-node.js';
+/**
+ * This builder can be used to create a `alter table` query.
+ */
 export class AlterTableBuilder {
     #props;
     constructor(props) {

package/dist/esm/schema/column-definition-builder.d.ts

@@ -6,11 +6,11 @@ import { AnyRawBuilder } from '../util/type-utils.js';
 import { DefaultValueExpression } from '../parser/default-value-parser.js';
 export interface ColumnDefinitionBuilderInterface<R> {
     /**
-     * Makes the column automatically incrementing.
+     * Adds `auto_increment` or `autoincrement` to the column definition
+     * depending on the dialect.
      *
-     * On some dialects this may change the column type as well. For example
-     * on postgres this sets the column type to `serial` no matter what you
-     * have specified before.
+     * Some dialects like PostgreSQL don't support this. On PostgreSQL
+     * you can use the `serial` or `bigserial` data type instead.
      */
     increments(): R;
     /**
@@ -23,6 +23,10 @@ export interface ColumnDefinitionBuilderInterface<R> {
     /**
      * Adds a foreign key constraint for the column.
      *
+     * If your database engine doesn't support foreign key constraints in the
+     * column definition (like MySQL 5) you need to call the table level
+     * {@link TableBuilder.addForeignKeyConstraint} method instead.
+     *
      * @example
      * ```ts
      * col.references('person.id')
@@ -31,6 +35,11 @@ export interface ColumnDefinitionBuilderInterface<R> {
     references(ref: string): R;
     /**
      * Adds an `on delete` constraint for the foreign key column.
+     *
+     * If your database engine doesn't support foreign key constraints in the
+     * column definition (like MySQL 5) you need to call the table level
+     * {@link TableBuilder.addForeignKeyConstraint} method instead.
+     *
      */
     onDelete(onDelete: OnModifyForeignAction): R;
     /**
@@ -64,7 +73,7 @@ export interface ColumnDefinitionBuilderInterface<R> {
      * ```ts
      * db.schema
      *   .createTable('pet')
-     *   .addColumn('number_of_legs', (col) => col.check('number_of_legs < 5', 'integer'))
+     *   .addColumn('number_of_legs', 'integer', (col) => col.check('number_of_legs < 5'))
      *   .execute()
      * ```
      */