Documentation / @zerotal/orm / index / ColumnBuilder

Class: ColumnBuilder<Locked>

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

Fluent per-column builder returned by every column-type method on Blueprint (e.g. table.string('email')). Modifier methods mutate the builder and return it for chaining; the column is compiled to a SQL fragment only when the surrounding Blueprint calls ColumnBuilder.toColumnSQL.

Remarks

SQLite is the primary dialect. Modifiers that have no SQLite representation (unsigned, comment, after, before, useCurrentOnUpdate) are accepted and tracked but emit no SQL there. Column modifications via ColumnBuilder.alter are dialect-specific and unsupported on SQLite (see Blueprint.toAlterSQL).

Example

table.string('email').unique().notNullable();
table.integer('age').unsigned().check('age >= 0').default(0);
table.uuid('id').primary();
table.dateTime('created_at').useCurrent();

Extended by

ForeignIdColumnBuilder

Type Parameters

Locked

Locked extends string = never

A phantom string union that accumulates the "traits" already applied. Once a trait is present, methods sharing that trait return never, so illegal re-application (e.g. .nullable().notNullable()) is a compile-time error rather than a runtime one. The lock a method participates in is noted as @locked in its docs; distinct traits can always be combined freely.

Constructors

Constructor

new ColumnBuilder<Locked>(name, _sqlType, isPrimary?, isAutoIncrement?): ColumnBuilder<Locked>

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

Parameters

name

string

_sqlType

string

isPrimary?

boolean = false

isAutoIncrement?

boolean = false

Returns

ColumnBuilder<Locked>

Constraints

unique()

unique(): "unique" extends Locked ? never : ColumnBuilder<Locked | "unique">

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

Add inline UNIQUE to the column definition.

Returns

"unique" extends Locked ? never : ColumnBuilder<Locked | "unique">

Locked

unique

index()

index(): "index" extends Locked ? never : ColumnBuilder<"index" | Locked>

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

"index" extends Locked ? never : ColumnBuilder<"index" | Locked>

Locked

index

primary()

primary(): "primary" extends Locked ? never : ColumnBuilder<Locked | "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

"primary" extends Locked ? never : ColumnBuilder<Locked | "primary">

Locked

primary

check()

check(expression): "check" extends Locked ? never : ColumnBuilder<Locked | "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

"check" extends Locked ? never : ColumnBuilder<Locked | "check">

Example

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

Locked

check

Modifiers

unsigned()

unsigned(): "unsigned" extends Locked ? never : ColumnBuilder<Locked | "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

"unsigned" extends Locked ? never : ColumnBuilder<Locked | "unsigned">

Locked

unsigned

storedAs()

storedAs(expression): "generated" extends Locked ? never : ColumnBuilder<Locked | "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

"generated" extends Locked ? never : ColumnBuilder<Locked | "generated">

Example

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

Locked

generated

virtualAs()

virtualAs(expression): "generated" extends Locked ? never : ColumnBuilder<Locked | "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

"generated" extends Locked ? never : ColumnBuilder<Locked | "generated">

Locked

generated

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

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

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

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

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

Nullability & defaults

nullable()

nullable(): "nullability" extends Locked ? never : ColumnBuilder<Locked | "nullability">

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

Allow NULL.

Returns

"nullability" extends Locked ? never : ColumnBuilder<Locked | "nullability">

Locked

nullability — shared with notNullable().

notNullable()

notNullable(): "nullability" extends Locked ? never : ColumnBuilder<Locked | "nullability">

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

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

Returns

"nullability" extends Locked ? never : ColumnBuilder<Locked | "nullability">

Locked

nullability — shared with nullable().

default()

default(value): "default" extends Locked ? never : ColumnBuilder<"default" | Locked>

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.

Parameters

value

unknown

The default value.

Returns

"default" extends Locked ? never : ColumnBuilder<"default" | Locked>

Locked

default

defaultTo()

defaultTo(value): "default" extends Locked ? never : ColumnBuilder<"default" | Locked>

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

Alias for ColumnBuilder.default — identical behaviour, common alternative name.

Parameters

value

unknown

Returns

"default" extends Locked ? never : ColumnBuilder<"default" | Locked>

Locked

default

useCurrent()

useCurrent(): "default" extends Locked ? never : ColumnBuilder<"default" | Locked>

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

Set the column default to CURRENT_TIMESTAMP. Useful for created_at-style columns without timestamps().

Returns

"default" extends Locked ? never : ColumnBuilder<"default" | Locked>

Locked

default

useCurrentOnUpdate()

useCurrentOnUpdate(): this

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

On MySQL / MariaDB: automatically update the column to CURRENT_TIMESTAMP on every row change. No-op on SQLite and PostgreSQL.

Returns

this

Other

name

readonly name: string

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