kysely 0.8.1 → 0.9.3

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

@@ -60,6 +60,8 @@ import { ForeignKeyConstraintNode } from '../operation-node/foreign-key-constrai
 import { ColumnDefinitionNode } from '../operation-node/column-definition-node.js';
 import { ModifyColumnNode } from '../operation-node/modify-column-node.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
+import { ColumnNode } from '../operation-node/column-node.js';
+import { UnionNode } from '../operation-node/union-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -67,6 +69,8 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected getSql(): string;
     protected visitSelectQuery(node: SelectQueryNode): void;
     protected visitFrom(node: FromNode): void;
+    protected visitSelection(node: SelectionNode): void;
+    protected visitColumn(node: ColumnNode): void;
     protected compileDistinctOn(selections: ReadonlyArray<SelectionNode>): void;
     protected compileList(nodes: ReadonlyArray<OperationNode>, separator?: string): void;
     protected visitWhere(node: WhereNode): void;
@@ -92,6 +96,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;
@@ -124,11 +129,12 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitModifyColumn(node: ModifyColumnNode): void;
     protected visitAddConstraint(node: AddConstraintNode): void;
     protected visitDropConstraint(node: DropConstraintNode): void;
+    protected visitUnion(node: UnionNode): void;
     protected append(str: string): void;
-    protected appendValue(value: PrimitiveValue): void;
+    protected appendValue(parameter: unknown): void;
     protected getLeftIdentifierWrapper(): string;
     protected getRightIdentifierWrapper(): string;
     protected getCurrentParameterPlaceholder(): string;
-    protected addParameter(parameter: any): void;
+    protected addParameter(parameter: unknown): 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 = [];
+    #sql = '';
     #parameters = [];
     get numParameters() {
         return this.#parameters.length;
     }
     compileQuery(node) {
-        this.#sqlFragments = [];
+        this.#sql = '';
         this.#parameters = [];
         this.visitNode(node);
         return freeze({
             sql: this.getSql(),
-            parameters: this.#parameters,
+            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.
@@ -61,6 +60,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.having);
         }
+        if (node.union) {
+            this.append(' ');
+            this.compileList(node.union, ' ');
+        }
         if (node.orderBy) {
             this.append(' ');
             this.visitNode(node.orderBy);
@@ -87,6 +90,12 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.append('from ');
         this.compileList(node.froms);
     }
+    visitSelection(node) {
+        this.visitNode(node.selection);
+    }
+    visitColumn(node) {
+        this.visitNode(node.column);
+    }
     compileDistinctOn(selections) {
         this.append('distinct on (');
         this.compileList(selections);
@@ -289,19 +298,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 +306,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 +325,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.visitNode(node.check);
         }
     }
+    getAutoIncrement() {
+        return 'auto_increment';
+    }
     visitReferences(node) {
         this.append('references ');
         this.visitNode(node.table);
@@ -633,11 +637,18 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.append('drop constraint ');
         this.visitNode(node.constraintName);
     }
+    visitUnion(node) {
+        this.append('union ');
+        if (node.all) {
+            this.append('all ');
+        }
+        this.visitNode(node.union);
+    }
     append(str) {
-        this.#sqlFragments.push(str);
+        this.#sql += str;
     }
-    appendValue(value) {
-        this.addParameter(value);
+    appendValue(parameter) {
+        this.addParameter(parameter);
         this.append(this.getCurrentParameterPlaceholder());
     }
     getLeftIdentifierWrapper() {
@@ -678,7 +689,7 @@ const SELECT_MODIFIER_SQL = {
     ForNoKeyUpdate: 'for no key update',
     ForUpdate: 'for update',
     ForShare: 'for share',
-    NoWait: 'no wait',
+    NoWait: 'nowait',
     SkipLocked: 'skip locked',
 };
 const JOIN_TYPE_SQL = {

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

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

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()
      * ```
      */

package/dist/esm/schema/create-schema-builder.js

@@ -9,7 +9,7 @@ export class CreateSchemaBuilder {
     ifNotExists() {
         return new CreateSchemaBuilder({
             ...this.#props,
-            createSchemaNode: CreateSchemaNode.cloneWithModifier(this.#props.createSchemaNode, 'IfNotExists'),
+            createSchemaNode: CreateSchemaNode.cloneWith(this.#props.createSchemaNode, { modifier: 'IfNotExists' }),
         });
     }
     toOperationNode() {

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

@@ -7,7 +7,10 @@ import { ColumnDefinitionBuilder } from './column-definition-builder.js';
 import { QueryId } from '../util/query-id.js';
 import { ForeignKeyConstraintBuilder } from './foreign-key-constraint-builder.js';
 import { DataTypeExpression } from '../parser/data-type-parser.js';
-export declare class CreateTableBuilder implements OperationNodeSource, Compilable {
+/**
+ * This builder can be used to create a `create table` query.
+ */
+export declare class CreateTableBuilder<TB extends string, C extends string = never> implements OperationNodeSource, Compilable {
     #private;
     constructor(props: CreateTableBuilderProps);
     /**
@@ -15,7 +18,7 @@ export declare class CreateTableBuilder implements OperationNodeSource, Compilab
      *
      * If the table already exists, no error is thrown if this method has been called.
      */
-    ifNotExists(): CreateTableBuilder;
+    ifNotExists(): CreateTableBuilder<TB, C>;
     /**
      * Adds a column to the table.
      *
@@ -23,44 +26,86 @@ export declare class CreateTableBuilder implements OperationNodeSource, Compilab
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('int', 'id', (col) => col.increments().primary()),
+     *   .addColumn('id', 'integer', (col) => col.increments().primaryKey()),
      *   .addColumn('first_name', 'varchar(50), (col) => col.notNull())
-     *   .addColumn('varchar', 'last_name')
-     *   .addColumn('numeric(8, 2)', 'bank_balance')
+     *   .addColumn('last_name', 'varchar')
+     *   .addColumn('bank_balance', 'numeric(8, 2)')
      *   .addColumn('data', db.raw('customtype'))
+     *   .addColumn('parent_id', 'integer', (col) =>
+     *     col.references('person.id').onDelete('cascade'))
+     *   )
+     * ```
+     *
+     * With this method, it's once again good to remember that Kysely just builds the query
+     * that's as close to the structure of your builder method calls as possible, and doesn't
+     * provide the same API for all databses. For example, some databases like older MySQL
+     * don't support `references` statement in the column definition. Instead foreign key
+     * constraints need to be defined in at the level of the `create table` query. See
+     * the next example:
+     *
+     * @example
+     * ```ts
+     *   .addColumn('parent_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'person_parent_id_fk', ['parent_id'], 'person', ['id'],
+     *     (cb) => cb.onDelete('cascade')
+     *   )
+     * ```
+     *
+     * Another good example is that PostgreSQL doesn't support the `auto_increment`
+     * keyword and you need to define an autoincrementing column for example using
+     * `serial`:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'serial', (col) => col.primaryKey()),
      * ```
      */
-    addColumn(columnName: string, dataType: DataTypeExpression, build?: ColumnBuilderCallback): CreateTableBuilder;
+    addColumn<CN extends string>(columnName: CN, dataType: DataTypeExpression, build?: ColumnBuilderCallback): CreateTableBuilder<TB, C | CN>;
     /**
      * Adds a primary key constraint for one or more columns.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
      * ```
      */
-    addPrimaryKeyConstraint(constraintName: string, columns: string[]): CreateTableBuilder;
+    addPrimaryKeyConstraint(constraintName: string, columns: C[]): CreateTableBuilder<TB, C>;
     /**
      * Adds a unique constraint for one or more columns.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
      * ```
      */
-    addUniqueConstraint(constraintName: string, columns: string[]): CreateTableBuilder;
+    addUniqueConstraint(constraintName: string, columns: C[]): CreateTableBuilder<TB, C>;
     /**
      * Adds a check constraint.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addCheckConstraint('check_legs', 'number_of_legs < 5')
      * ```
      */
-    addCheckConstraint(constraintName: string, checkExpression: string): CreateTableBuilder;
+    addCheckConstraint(constraintName: string, checkExpression: string): CreateTableBuilder<TB, C>;
     /**
      * Adds a foreign key constraint.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addForeignKeyConstraint(
@@ -82,7 +127,7 @@ export declare class CreateTableBuilder implements OperationNodeSource, Compilab
      * )
      * ```
      */
-    addForeignKeyConstraint(constraintName: string, columns: string[], targetTable: string, targetColumns: string[], build?: ForeignKeyConstraintBuilderCallback): CreateTableBuilder;
+    addForeignKeyConstraint(constraintName: string, columns: C[], targetTable: string, targetColumns: string[], build?: ForeignKeyConstraintBuilderCallback): CreateTableBuilder<TB, C>;
     toOperationNode(): CreateTableNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

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

@@ -2,12 +2,18 @@ import { ColumnDefinitionNode } from '../operation-node/column-definition-node.j
 import { CreateTableNode } from '../operation-node/create-table-node.js';
 import { preventAwait } from '../util/prevent-await.js';
 import { ColumnDefinitionBuilder } from './column-definition-builder.js';
-import { freeze } from '../util/object-utils.js';
+import { freeze, noop } from '../util/object-utils.js';
 import { ForeignKeyConstraintNode } from '../operation-node/foreign-key-constraint-node.js';
 import { ColumnNode } from '../operation-node/column-node.js';
 import { TableNode } from '../operation-node/table-node.js';
 import { ForeignKeyConstraintBuilder } from './foreign-key-constraint-builder.js';
 import { parseDataTypeExpression, } from '../parser/data-type-parser.js';
+import { PrimaryConstraintNode } from '../operation-node/primary-constraint-node.js';
+import { UniqueConstraintNode } from '../operation-node/unique-constraint-node.js';
+import { CheckConstraintNode } from '../operation-node/check-constraint-node.js';
+/**
+ * This builder can be used to create a `create table` query.
+ */
 export class CreateTableBuilder {
     #props;
     constructor(props) {
@@ -31,18 +37,45 @@ export class CreateTableBuilder {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('int', 'id', (col) => col.increments().primary()),
+     *   .addColumn('id', 'integer', (col) => col.increments().primaryKey()),
      *   .addColumn('first_name', 'varchar(50), (col) => col.notNull())
-     *   .addColumn('varchar', 'last_name')
-     *   .addColumn('numeric(8, 2)', 'bank_balance')
+     *   .addColumn('last_name', 'varchar')
+     *   .addColumn('bank_balance', 'numeric(8, 2)')
      *   .addColumn('data', db.raw('customtype'))
+     *   .addColumn('parent_id', 'integer', (col) =>
+     *     col.references('person.id').onDelete('cascade'))
+     *   )
+     * ```
+     *
+     * With this method, it's once again good to remember that Kysely just builds the query
+     * that's as close to the structure of your builder method calls as possible, and doesn't
+     * provide the same API for all databses. For example, some databases like older MySQL
+     * don't support `references` statement in the column definition. Instead foreign key
+     * constraints need to be defined in at the level of the `create table` query. See
+     * the next example:
+     *
+     * @example
+     * ```ts
+     *   .addColumn('parent_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'person_parent_id_fk', ['parent_id'], 'person', ['id'],
+     *     (cb) => cb.onDelete('cascade')
+     *   )
+     * ```
+     *
+     * Another good example is that PostgreSQL doesn't support the `auto_increment`
+     * keyword and you need to define an autoincrementing column for example using
+     * `serial`:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'serial', (col) => col.primaryKey()),
      * ```
      */
-    addColumn(columnName, dataType, build) {
-        let columnBuilder = new ColumnDefinitionBuilder(ColumnDefinitionNode.create(columnName, parseDataTypeExpression(dataType)));
-        if (build) {
-            columnBuilder = build(columnBuilder);
-        }
+    addColumn(columnName, dataType, build = noop) {
+        const columnBuilder = build(new ColumnDefinitionBuilder(ColumnDefinitionNode.create(columnName, parseDataTypeExpression(dataType))));
         return new CreateTableBuilder({
             ...this.#props,
             createTableNode: CreateTableNode.cloneWithColumn(this.#props.createTableNode, columnBuilder.toOperationNode()),
@@ -51,6 +84,9 @@ export class CreateTableBuilder {
     /**
      * Adds a primary key constraint for one or more columns.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
@@ -59,12 +95,15 @@ export class CreateTableBuilder {
     addPrimaryKeyConstraint(constraintName, columns) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithPrimaryKeyConstraint(this.#props.createTableNode, constraintName, columns),
+            createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, PrimaryConstraintNode.create(columns, constraintName)),
         });
     }
     /**
      * Adds a unique constraint for one or more columns.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
@@ -73,12 +112,15 @@ export class CreateTableBuilder {
     addUniqueConstraint(constraintName, columns) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithUniqueConstraint(this.#props.createTableNode, constraintName, columns),
+            createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, UniqueConstraintNode.create(columns, constraintName)),
         });
     }
     /**
      * Adds a check constraint.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addCheckConstraint('check_legs', 'number_of_legs < 5')
@@ -87,12 +129,15 @@ export class CreateTableBuilder {
     addCheckConstraint(constraintName, checkExpression) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithCheckConstraint(this.#props.createTableNode, constraintName, checkExpression),
+            createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, CheckConstraintNode.create(checkExpression, constraintName)),
         });
     }
     /**
      * Adds a foreign key constraint.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addForeignKeyConstraint(
@@ -114,14 +159,11 @@ export class CreateTableBuilder {
      * )
      * ```
      */
-    addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns, build) {
-        let builder = new ForeignKeyConstraintBuilder(ForeignKeyConstraintNode.create(columns.map(ColumnNode.create), TableNode.create(targetTable), targetColumns.map(ColumnNode.create), constraintName));
-        if (build) {
-            builder = build(builder);
-        }
+    addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns, build = noop) {
+        const builder = build(new ForeignKeyConstraintBuilder(ForeignKeyConstraintNode.create(columns.map(ColumnNode.create), TableNode.create(targetTable), targetColumns.map(ColumnNode.create), constraintName)));
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithForeignKeyConstraint(this.#props.createTableNode, builder.toOperationNode()),
+            createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, builder.toOperationNode()),
         });
     }
     toOperationNode() {

package/dist/esm/schema/schema.d.ts

@@ -22,14 +22,49 @@ export declare class SchemaModule {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'int', col => col.primaryKey().increments())
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
      *   .addColumn('first_name', 'varchar', col => col.notNull())
      *   .addColumn('last_name', 'varchar', col => col.notNull())
      *   .addColumn('gender', 'varchar')
      *   .execute()
      * ```
+     *
+     * @example
+     * This example creates a table with a foreign key. Not all database
+     * engines support column-level foreign key constraint definitions.
+     * For example if you are using MySQL 5.X see the next example after
+     * this one.
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer', col => col
+     *     .references('person.id')
+     *     .onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * @example
+     * This example adds a foreign key constraint for a columns just
+     * like the previous example, but using a table-level statement.
+     * On MySQL 5.X you need to define foreign key constraints like
+     * this:
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'pet_owner_id_foreign', ['owner_id'], 'person', ['id'],
+     *     (constraint) => constraint.onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
      */
-    createTable(table: string): CreateTableBuilder;
+    createTable<TB extends string>(table: TB): CreateTableBuilder<TB, never>;
     /**
      * Drop a table.
      *