references()

Signature

references() — returns any

Available in: tabledefinition Category: Table Definition Functions

Description

Adds integer reference columns to the table definition and (unless foreignKey=false or polymorphic=true) registers a matching foreign-key constraint. The column suffix depends on the useUnderscoreReferenceColumns setting: false (framework default) → id; true (default for apps generated by wheels new) → _id, matching Wheels model belongsTo defaults. With polymorphic=true, a type / _type companion column is added and no FK is registered. Accepts columnNames as an alias for referenceNames (per #2781) — both are list-shaped (single name or comma-delimited). New code should use columnNames for consistency with every other column helper here.

Parameters

Name	Type	Required	Default	Description
referenceNames	string	no	—	Comma-delimited list of reference base names (e.g. "user,role"). Each produces a <name>_id (or <name>id) column. Legacy parameter — columnNames is the modern alias.
columnNames	string	no	—	Modern alias for referenceNames. Pass one or the other — not both.
default	any	no	—	Default value for the generated integer column(s).
allowNull	boolean	no	false	If true, the generated column(s) allow NULL.
polymorphic	boolean	no	false	If true, also creates a <name>type / <name>_type companion column and skips the foreign-key constraint.
foreignKey	boolean	no	true	If true (default), registers a foreign key on the generated column. Ignored when polymorphic=true.
onUpdate	string	no	—	Foreign-key ON UPDATE clause. Engine-specific values; common: "cascade", "null", "none".
onDelete	string	no	—	Foreign-key ON DELETE clause. Same value set as onUpdate.
referenceColumn	string	no	id	Referenced PK column. Default remains "id" (public API — do not flip).

Examples

// The generated column suffix depends on the `useUnderscoreReferenceColumns` setting:
// `true` (the default for apps generated by `wheels new`) produces `<name>_id` / `<name>_type`,
// matching Wheels model `belongsTo` defaults; `false` (the framework default for existing apps)
// produces `<name>id` / `<name>type`. The examples below show both outcomes.

// 1. Add a single reference column with a foreign key constraint
// Creates a `user_id` (or `userid`) integer column and a foreign key pointing to the `users` table.
t = createTable(name='posts');
	t.string(columnNames='title', limit=255, allowNull=false);
	t.references(columnNames='user');
	t.timestamps();
t.create();

// 2. Add multiple reference columns at once
// Creates `author_id` and `category_id` (or `authorid` and `categoryid`) integer columns,
// each with a foreign key.
t = createTable(name='articles');
	t.string(columnNames='title', limit=255, allowNull=false);
	t.references(columnNames='author,category');
	t.timestamps();
t.create();

// 3. Add a polymorphic reference (no foreign key, adds a `<name>_type` / `<name>type` string column)
// Creates `commentable_id` (integer) and `commentable_type` (string) columns
// (or `commentableid` / `commentabletype` when `useUnderscoreReferenceColumns` is `false`).
t = createTable(name='comments');
	t.text(columnNames='body', allowNull=false);
	t.references(columnNames='commentable', polymorphic=true);
	t.timestamps();
t.create();

// 4. Add a reference with cascade delete and allow null
// The legacy `referenceNames=` argument is still accepted as an alias for `columnNames=`.
t = createTable(name='attachments');
	t.references(columnNames='post', allowNull=true, onDelete='cascade');
	t.string(columnNames='fileName', limit=255);
	t.timestamps();
t.create();