Documentation

Documentation / @zerotal/orm / index / Blueprint

Class: Blueprint

Defined in: packages/orm/src/schema/Blueprint.ts:72

The fluent table builder passed as table to the callbacks of Schema.create, Schema.createIfNotExists and Schema.table.

Each method call records an intent (a column, an index, a foreign key, a drop, a rename) on the blueprint; the accumulated intent is compiled to SQL only when the surrounding Schema helper calls Blueprint.toCreateSQL (for create) or Blueprint.toAlterSQL (for table). Column-type methods return a ColumnBuilder (or ForeignIdColumnBuilder) so per-column modifiers can be chained; table-level methods return this so index and constraint calls can be chained.

Remarks

This ORM targets SQLite (via Bun.sql) as its primary dialect, so the concrete storage type of every column collapses to one of SQLite's storage classes: INTEGER, REAL, TEXT or BLOB. The many distinct column-type methods (bigInteger, mediumText, char, decimal, …) exist for a familiar, expressive schema API and multi-database portability, but on SQLite several of them compile to the same underlying type and length/precision arguments are accepted yet ignored. Notes on the affected methods call this out. Dialect-specific behaviour (MySQL MODIFY COLUMN, PostgreSQL per-attribute ALTER COLUMN, fulltext/spatial indexes) is only exercised on the ALTER path via Blueprint.toAlterSQL.

Example

await Schema.create('posts', (table) => {
  table.id();
  table.string('title');
  table.text('body').nullable();
  table.enum('status', ['draft', 'published']).default('draft');
  table.foreignId('author_id').constrained('users').cascadeOnDelete();
  table.timestamps();

  table.unique('title');
  table.index(['status', 'author_id']);
});

Constructors

Constructor

new Blueprint(): Blueprint

Returns

Blueprint

Column types

id()

id(name?): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:93

Auto-incrementing integer primary key. Shorthand: table.id() is identical to table.increments('id').

Parameters

name?

string = "id"

Column name, defaults to "id".

Returns

ColumnBuilder

The column builder for the new INTEGER PRIMARY KEY AUTOINCREMENT column.

increments()

increments(name?): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:103

Auto-incrementing INTEGER PRIMARY KEY AUTOINCREMENT column.

Parameters

name?

string = "id"

Column name, defaults to "id".

Returns

ColumnBuilder

bigIncrements()

bigIncrements(name?): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:114

Auto-incrementing big-integer primary key. On SQLite this is identical to Blueprint.increments (both use the INTEGER storage class).

Parameters

name?

string = "id"

Column name, defaults to "id".

Returns

ColumnBuilder

integer()

integer(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:122

Signed INTEGER column.

Parameters

name

string

Returns

ColumnBuilder

bigInteger()

bigInteger(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:130

Big-integer column. Stored as INTEGER on SQLite (no distinct BIGINT type).

Parameters

name

string

Returns

ColumnBuilder

tinyInteger()

tinyInteger(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:138

Tiny-integer column. Stored as INTEGER on SQLite.

Parameters

name

string

Returns

ColumnBuilder

smallInteger()

smallInteger(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:146

Small-integer column. Stored as INTEGER on SQLite.

Parameters

name

string

Returns

ColumnBuilder

mediumInteger()

mediumInteger(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:154

Medium-integer column. Stored as INTEGER on SQLite.

Parameters

name

string

Returns

ColumnBuilder

unsignedInteger()

unsignedInteger(name): ColumnBuilder<"unsigned">

Defined in: packages/orm/src/schema/Blueprint.ts:163

Unsigned integer column. The unsigned flag is tracked for multi-DB compatibility only — SQLite has no UNSIGNED type, so no extra SQL is emitted.

Parameters

name

string

Returns

ColumnBuilder<"unsigned">

unsignedBigInteger()

unsignedBigInteger(name): ColumnBuilder<"unsigned">

Defined in: packages/orm/src/schema/Blueprint.ts:172

Unsigned big-integer column — the conventional type for foreign-key columns. Stored as INTEGER on SQLite.

Parameters

name

string

Returns

ColumnBuilder<"unsigned">

unsignedSmallInteger()

unsignedSmallInteger(name): ColumnBuilder<"unsigned">

Defined in: packages/orm/src/schema/Blueprint.ts:180

Unsigned small-integer column. Stored as INTEGER on SQLite.

Parameters

name

string

Returns

ColumnBuilder<"unsigned">

unsignedTinyInteger()

unsignedTinyInteger(name): ColumnBuilder<"unsigned">

Defined in: packages/orm/src/schema/Blueprint.ts:188

Unsigned tiny-integer column. Stored as INTEGER on SQLite.

Parameters

name

string

Returns

ColumnBuilder<"unsigned">

unsignedMediumInteger()

unsignedMediumInteger(name): ColumnBuilder<"unsigned">

Defined in: packages/orm/src/schema/Blueprint.ts:196

Unsigned medium-integer column. Stored as INTEGER on SQLite.

Parameters

name

string

Returns

ColumnBuilder<"unsigned">

string()

string(name, _length?): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:208

Variable-length string column (VARCHAR-style), stored as TEXT.

Parameters

name

string

Column name.

_length?

number = 255

Max length; accepted for multi-DB compatibility but ignored on SQLite.

Returns

ColumnBuilder

char()

char(name, _length?): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:216

Fixed-length CHAR column. Stored as TEXT on SQLite; _length is ignored.

Parameters

name

string

_length?

number = 255

Returns

ColumnBuilder

text()

text(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:224

TEXT column for arbitrary-length strings.

Parameters

name

string

Returns

ColumnBuilder

tinyText()

tinyText(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:232

Tiny-text column. Stored as TEXT on SQLite.

Parameters

name

string

Returns

ColumnBuilder

mediumText()

mediumText(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:240

Medium-text column. Stored as TEXT on SQLite.

Parameters

name

string

Returns

ColumnBuilder

longText()

longText(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:248

Long-text column. Stored as TEXT on SQLite.

Parameters

name

string

Returns

ColumnBuilder

uuid()

uuid(name): ColumnBuilder

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

UUID column — stored as TEXT (36 chars).

Parameters

name

string

Returns

ColumnBuilder

Example

table.uuid('id').primary();
table.uuid('id').primary().defaultTo(sql`gen_random_uuid()`);

ulid()

ulid(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:273

ULID column — stored as TEXT (26 chars). ULIDs are lexicographically sortable and URL-safe.

Parameters

name

string

Returns

ColumnBuilder

float()

float(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:283

Single-precision floating-point column, stored as REAL.

Parameters

name

string

Returns

ColumnBuilder

double()

double(name, _precision?, _scale?): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:292

Double-precision floating-point column, stored as REAL. _precision/_scale are accepted for multi-DB compatibility but ignored on SQLite.

Parameters

name

string

_precision?

number

_scale?

number

Returns

ColumnBuilder

decimal()

decimal(name, _precision?, _scale?): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:301

Fixed-point decimal column. Stored as REAL on SQLite (no exact DECIMAL type); _precision/_scale are accepted but ignored.

Parameters

name

string

_precision?

number = 8

_scale?

number = 2

Returns

ColumnBuilder

unsignedDecimal()

unsignedDecimal(name, _precision?, _scale?): ColumnBuilder<"unsigned">

Defined in: packages/orm/src/schema/Blueprint.ts:310

Unsigned fixed-point decimal column. Stored as REAL on SQLite; the unsigned flag is tracked for compatibility only.

Parameters

name

string

_precision?

number = 8

_scale?

number = 2

Returns

ColumnBuilder<"unsigned">

boolean()

boolean(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:321

Boolean column. Stored as INTEGER (0 / 1); JS booleans passed to ColumnBuilder.default serialise to 1 / 0.

Parameters

name

string

Returns

ColumnBuilder

dateTime()

dateTime(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:331

Date-and-time column, stored as TEXT (ISO-8601).

Parameters

name

string

Returns

ColumnBuilder

timestamp()

timestamp(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:339

Timestamp column. Alias of Blueprint.dateTime — stored as TEXT (ISO-8601).

Parameters

name

string

Returns

ColumnBuilder

date()

date(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:347

Date-only column, stored as TEXT (YYYY-MM-DD).

Parameters

name

string

Returns

ColumnBuilder

time()

time(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:355

Time-of-day column, stored as TEXT (HH:MM:SS).

Parameters

name

string

Returns

ColumnBuilder

year()

year(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:363

4-digit year column, stored as INTEGER.

Parameters

name

string

Returns

ColumnBuilder

binary()

binary(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:373

Binary column, stored as BLOB.

Parameters

name

string

Returns

ColumnBuilder

json()

json(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:383

JSON column, stored as TEXT (serialised JSON).

Parameters

name

string

Returns

ColumnBuilder

enum()

enum(name, values): ColumnBuilder<"check">

Defined in: packages/orm/src/schema/Blueprint.ts:401

Enum column — stored as TEXT with a CHECK constraint enforcing the allowed values. Single quotes in values are escaped.

Parameters

name

string

Column name.

values

string[]

The permitted string values.

Returns

ColumnBuilder<"check">

Example

table.enum('status', ['active', 'inactive', 'suspended']);

set()

set(name, _values): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:412

MySQL SET column — stored as TEXT on SQLite. Unlike Blueprint.enum, no CHECK constraint is emitted, so _values is not enforced on SQLite.

Parameters

name

string

_values

string[]

Returns

ColumnBuilder

ipAddress()

ipAddress(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:422

IPv4 / IPv6 address column — stored as TEXT (up to 45 chars for IPv6).

Parameters

name

string

Returns

ColumnBuilder

macAddress()

macAddress(name): ColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:430

MAC address column — stored as TEXT (17 chars, xx:xx:xx:xx:xx:xx).

Parameters

name

string

Returns

ColumnBuilder

Dropping

dropColumn()

dropColumn(...names): this

Defined in: packages/orm/src/schema/Blueprint.ts:633

Drop one or more columns (ALTER TABLE … DROP COLUMN). Only meaningful on the ALTER path, i.e. inside a Schema.table callback.

Parameters

names

...string[]

Returns

this

dropIndex()

dropIndex(nameOrColumns): this

Defined in: packages/orm/src/schema/Blueprint.ts:652

Drop an index by name, or by deriving {table}_{cols}_index from a column list. Emits DROP INDEX IF EXISTS; a no-op when the name cannot be determined.

Parameters

nameOrColumns

string | string[]

Returns

this

dropUnique()

dropUnique(nameOrColumns): this

Defined in: packages/orm/src/schema/Blueprint.ts:662

Drop a unique index. On SQLite unique constraints are implemented as indexes, so this is identical to Blueprint.dropIndex.

Parameters

nameOrColumns

string | string[]

Returns

this

dropForeign()

dropForeign(nameOrColumns): this

Defined in: packages/orm/src/schema/Blueprint.ts:673

Drop a foreign-key constraint by name (or derived {table}_{cols}_foreign). Emits ALTER TABLE … DROP FOREIGN KEY (MySQL) / DROP CONSTRAINT (Postgres). No SQL is emitted on SQLite, which cannot drop FK constraints without a full table rebuild — use a rebuild migration there.

Parameters

nameOrColumns

string | string[]

Returns

this

dropPrimary()

dropPrimary(): this

Defined in: packages/orm/src/schema/Blueprint.ts:686

Drop the table primary key.

Returns

this

Remarks

Currently a no-op for every dialect: it records no intent and emits no SQL. Dropping a primary key on SQLite requires a full table rebuild.

Foreign keys

foreignId()

foreignId(name): ForeignIdColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:448

Unsigned big-integer foreign-key column. Chain .constrained() on the returned ForeignIdColumnBuilder to add the FOREIGN KEY constraint automatically, inferring the referenced table from the column name.

table.foreignId('user_id').constrained().nullOnDelete();
table.foreignId('post_id').constrained('blog_posts');

Parameters

name

string

Returns

ForeignIdColumnBuilder

foreignUuid()

foreignUuid(name): ForeignIdColumnBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:465

UUID (TEXT) foreign-key column. Chain .constrained() on the returned ForeignIdColumnBuilder to add the FK constraint:

table.foreignUuid('user_id').constrained();

Parameters

name

string

Returns

ForeignIdColumnBuilder

foreign()

foreign(column): ForeignKeyBuilder

Defined in: packages/orm/src/schema/Blueprint.ts:561

Begin an explicit foreign-key constraint on an existing column, returning a ForeignKeyBuilder to configure the referenced table/column and referential actions.

Parameters

column

string

Returns

ForeignKeyBuilder

Example

table.foreign('user_id').references('id').on('users').onDelete('CASCADE');

Indexes

primary()

primary(columns, _name?): this

Defined in: packages/orm/src/schema/Blueprint.ts:581

Define a table-level (optionally composite) primary key. Only applied on CREATE TABLE and only when no column already declares itself the primary key.

Parameters

columns

string | string[]

One column name or several for a composite key.

_name?

string

Constraint name; accepted for compatibility but unused on SQLite.

Returns

this

Example

table.primary(['user_id', 'role_id']);

index()

index(columns, name?): this

Defined in: packages/orm/src/schema/Blueprint.ts:591

Add a non-unique index across one or more columns. When name is omitted the index name is derived as {table}_{cols}_index.

Parameters

columns

string | string[]

name?

string

Returns

this

unique()

unique(columns, name?): this

Defined in: packages/orm/src/schema/Blueprint.ts:601

Add a unique index across one or more columns. When name is omitted the index name is derived as {table}_{cols}_unique.

Parameters

columns

string | string[]

name?

string

Returns

this

fulltext()

fulltext(columns, name?): this

Defined in: packages/orm/src/schema/Blueprint.ts:612

Full-text index. On MySQL/Postgres this is intended to emit a FULLTEXT/GIN index; on SQLite a plain CREATE INDEX is emitted (use FTS5 virtual tables for true full-text search there).

Parameters

columns

string | string[]

name?

string

Returns

this

spatialIndex()

spatialIndex(columns, name?): this

Defined in: packages/orm/src/schema/Blueprint.ts:621

Spatial (GIS) index. Falls back to a plain CREATE INDEX on SQLite.

Parameters

columns

string | string[]

name?

string

Returns

this

Table modifiers

timestamps()

timestamps(): void

Defined in: packages/orm/src/schema/Blueprint.ts:477

Add nullable created_at and updated_at (TEXT) columns.

Returns

void

nullableTimestamps()

nullableTimestamps(): void

Defined in: packages/orm/src/schema/Blueprint.ts:486

Alias for Blueprint.timestamps — both columns are always nullable.

Returns

void

softDeletes()

softDeletes(column?): void

Defined in: packages/orm/src/schema/Blueprint.ts:495

Add a nullable deleted_at (TEXT) column for soft-delete support.

Parameters

column?

string = "deleted_at"

Column name, defaults to "deleted_at".

Returns

void

rememberToken()

rememberToken(): ColumnBuilder<"nullability">

Defined in: packages/orm/src/schema/Blueprint.ts:504

Add remember_token — a nullable 100-char string used by session-based "remember me" functionality.

Returns

ColumnBuilder<"nullability">

morphs()

morphs(name, indexName?): void

Defined in: packages/orm/src/schema/Blueprint.ts:521

Add {name}_id (unsigned big-integer) and {name}_type (string) columns plus a composite index — the standard polymorphic-relation pattern.

Parameters

name

string

Relation base name (e.g. "taggable").

indexName?

string

Optional explicit name for the composite index.

Returns

void

Example

table.morphs('taggable');
// adds: taggable_id INTEGER, taggable_type TEXT, index on both

nullableMorphs()

nullableMorphs(name, indexName?): void

Defined in: packages/orm/src/schema/Blueprint.ts:531

Same as Blueprint.morphs but both columns are nullable.

Parameters

name

string

indexName?

string

Returns

void

uuidMorphs()

uuidMorphs(name, indexName?): void

Defined in: packages/orm/src/schema/Blueprint.ts:542

UUID-based polymorphic relation columns: {name}_id (TEXT UUID) and {name}_type (string) plus a composite index.

Parameters

name

string

indexName?

string

Returns

void

renameColumn()

renameColumn(from, to): this

Defined in: packages/orm/src/schema/Blueprint.ts:642

Rename a column (ALTER TABLE … RENAME COLUMN from TO to).

Parameters

from

string

to

string

Returns

this

toCreateSQL()

toCreateSQL(table, dialect?): string[]

Defined in: packages/orm/src/schema/Blueprint.ts:701

Compile the accumulated column/constraint/index intent into the statements that create the table. Called by Schema.create.

Parameters

table

string

Target table name.

dialect?

"sqlite" | "postgres" | "mysql"

Returns

string[]

[ "CREATE TABLE …", ...("CREATE INDEX …")* ] — the create statement first, followed by one statement per index.

toAlterSQL()

toAlterSQL(table, dialect?): string[]

Defined in: packages/orm/src/schema/Blueprint.ts:728

Compile the accumulated intent into ALTER TABLE / CREATE INDEX IF NOT EXISTS / DROP INDEX statements. Called by Schema.table.

Parameters

table

string

Target table name.

dialect?

"sqlite" | "postgres" | "mysql"

Governs column-modification and drop-foreign SQL; defaults to "sqlite".

Returns

string[]

The ordered list of DDL statements to execute.