Documentation / @zerotal/orm / index / ForeignIdColumnBuilder

Class: ForeignIdColumnBuilder

Defined in: packages/orm/src/schema/ColumnDefinition.ts:365

Returned by foreignId() and foreignUuid(). Extends ColumnBuilder with a .constrained() helper that wires the foreign-key constraint, inferring the referenced table from the column name.

Example

table.foreignId('user_id').constrained();                  // → users.id
  table.foreignId('author_id').constrained('users');          // → users.id
  table.foreignId('author_id').constrained('users', 'uuid');  // → users.uuid
  table.foreignId('user_id').nullable().constrained().nullOnDelete();

Extends

ColumnBuilder

Constructors

Constructor

new ForeignIdColumnBuilder(name, sqlType, _addFk): ForeignIdColumnBuilder

Defined in: packages/orm/src/schema/ColumnDefinition.ts:366

Parameters

name

string

sqlType

string

_addFk

(col) => ForeignKeyBuilder

Returns

ForeignIdColumnBuilder

Overrides

ColumnBuilder.constructor

Constraints

unique()

unique(): ColumnBuilder<"unique">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:144

Add inline UNIQUE to the column definition.

Returns

ColumnBuilder<"unique">

Locked

unique

Inherited from

ColumnBuilder.unique

index()

index(): ColumnBuilder<"index">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:155

Request a standalone CREATE INDEX on this column after the table is created. Ignored when the column is also unique() (a unique index already covers it).

Returns

ColumnBuilder<"index">

Locked

index

Inherited from

ColumnBuilder.index

primary()

primary(): ColumnBuilder<"primary">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:177

Promote this column to the primary key. Use this when you need a PK without auto-increment (e.g. UUID PKs).

Returns

ColumnBuilder<"primary">

Locked

primary

Inherited from

ColumnBuilder.primary

check()

check(expression): ColumnBuilder<"check">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:194

Add a CHECK (expression) constraint.

Parameters

expression

string

A raw SQL boolean expression; not escaped or validated.

Returns

ColumnBuilder<"check">

Example

table.integer('age').unsigned().check('age >= 0');
table.string('status').check("status IN ('active','inactive')");

Locked

check

Inherited from

ColumnBuilder.check

Foreign keys

constrained()

constrained(table?, column?): ForeignKeyBuilder

Defined in: packages/orm/src/schema/ColumnDefinition.ts:386

Add a FOREIGN KEY constraint for this column. The referenced table is inferred from the column name (user_id → users) unless supplied explicitly; note the inference is naive — it strips a trailing _id and appends s, so irregular plurals (category_id → categorys) need an explicit table argument.

Parameters

table?

string

Referenced table; defaults to the name inferred from the column.

column?

string = "id"

Referenced column; defaults to "id".

Returns

ForeignKeyBuilder

The ForeignKeyBuilder so .onDelete() etc. can be chained.

Modifiers

unsigned()

unsigned(): ColumnBuilder<"unsigned">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:166

Mark the column as unsigned. Tracked for documentation and multi-DB compatibility — SQLite has no UNSIGNED type so no SQL is emitted.

Returns

ColumnBuilder<"unsigned">

Locked

unsigned

Inherited from

ColumnBuilder.unsigned

storedAs()

storedAs(expression): ColumnBuilder<"generated">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:210

Define a generated stored column (computed and physically stored). Requires SQLite ≥ 3.31.

Parameters

expression

string

Returns

ColumnBuilder<"generated">

Example

table.string('full_name').storedAs("first_name || ' ' || last_name");

Locked

generated

Inherited from

ColumnBuilder.storedAs

virtualAs()

virtualAs(expression): ColumnBuilder<"generated">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:223

Define a generated virtual column (computed on read, never stored). Requires SQLite ≥ 3.31.

Parameters

expression

string

Returns

ColumnBuilder<"generated">

Locked

generated

Inherited from

ColumnBuilder.virtualAs

alter()

alter(): this

Defined in: packages/orm/src/schema/ColumnDefinition.ts:246

Mark this column as a modification of an existing column rather than a new addition. Used inside Schema.table callbacks:

Schema.table('users', (table) => {
  table.string('password').nullable().alter();
});

On MySQL / MariaDB emits MODIFY COLUMN; on PostgreSQL each attribute change becomes a separate ALTER COLUMN sub-command. On SQLite this is a no-op — a console warning is emitted and the statement is skipped (structural changes require a full table rebuild).

Returns

this

Inherited from

ColumnBuilder.alter

change()

change(): this

Defined in: packages/orm/src/schema/ColumnDefinition.ts:255

Alias of ColumnBuilder.alter — mark this as a modification of an existing column.

Returns

this

Inherited from

ColumnBuilder.change

comment()

comment(_text): this

Defined in: packages/orm/src/schema/ColumnDefinition.ts:264

Attach a column comment. No-op on SQLite; intended to emit a COMMENT on MySQL/Postgres.

Parameters

_text

string

Returns

this

Inherited from

ColumnBuilder.comment

after()

after(_column): this

Defined in: packages/orm/src/schema/ColumnDefinition.ts:274

Place this column after column in the table (MySQL / MariaDB only). Accepted but ignored on SQLite and PostgreSQL.

Parameters

_column

string

Returns

this

Inherited from

ColumnBuilder.after

before()

before(_column): this

Defined in: packages/orm/src/schema/ColumnDefinition.ts:284

Place this column before column in the table (MySQL / MariaDB only). No-op on SQLite / PostgreSQL.

Parameters

_column

string

Returns

this

Inherited from

ColumnBuilder.before

Nullability & defaults

nullable()

nullable(): ColumnBuilder<"nullability">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:79

Allow NULL.

Returns

ColumnBuilder<"nullability">

Locked

nullability — shared with notNullable().

Inherited from

ColumnBuilder.nullable

notNullable()

notNullable(): ColumnBuilder<"nullability">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:89

Enforce NOT NULL explicitly (the default for non-PK columns).

Returns

ColumnBuilder<"nullability">

Locked

nullability — shared with nullable().

Inherited from

ColumnBuilder.notNullable

default()

default(value): ColumnBuilder<"default">

Defined in: packages/orm/src/schema/ColumnDefinition.ts:101

Add a DEFAULT clause. null serialises to NULL, JS booleans to 1 / 0, strings are single-quoted (with quotes escaped), everything else stringified.