Migrator: primaryKey(name=...) is an argument-naming outlier

[bpamiri]

Spun off from #2781 audit.

`TableDefinition.cfc::primaryKey()` uses `required string name` for the column-name argument:

```cfm
public any function primaryKey(
required string name,
string type = "integer",
...
)
```

Every sibling column helper in the same file (`bigInteger`, `binary`, `boolean`, `date`, `datetime`, `decimal`, `float`, `integer`, `string`, `text`, `uniqueidentifier`, `time`, `timestamp`, `char`) accepts `columnNames` (or singular `columnName` via `$combineArguments`). `primaryKey` is the lone outlier — users and AI tooling that learn the convention from one helper consistently mis-call `primaryKey` with `columnName=...` and get a "required argument missing" error.

Defense for keeping it

The primary key IS the row's identity, not a payload column. Calling it `name` is more semantic than calling it `columnName`. The argument has been `name` since the 2017 dbmigrate merge.

Defense for changing it

Predictability beats cleverness. Every other column-shaped helper in the file uses `columnNames`/`columnName`; one outlier costs more attention than the semantic distinction earns. Same fix as #2781 worked for `t.references()`: accept the conventional alias via `$combineArguments`, keep the legacy name working.

Suggested fix

```cfm
public any function primaryKey(
string name,
string columnName,
string columnNames,
...
) {
$combineArguments(args = arguments, combine = "name,columnName", required = false);
$combineArguments(args = arguments, combine = "name,columnNames", required = true);
// ...
}
```

Three-way alias: `name` (legacy), `columnName` (singular convention), `columnNames` (plural convention). All resolve to `arguments.name` internally so the existing body stays unchanged.

Confidence

Low-priority cleanup. Issue is purely cosmetic — `primaryKey` works fine, just doesn't match the surrounding pattern. No downstream bugs.

Good first issue for someone wanting to touch the migrator without a deep dive.

[wheels-bot]

Wheels Bot — Triage

Classified as framework-design (API/feature design question).
Cross-framework research will follow shortly — Rails, Laravel, Django,
and other modern frameworks will be consulted before any path forward
is proposed.

<!-- wheels-bot:triage:2803 -->
<!-- wheels-bot:triage-class:framework-design -->

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

Should TableDefinition.primaryKey(name=...) accept columnName/columnNames aliases (via $combineArguments) to align with every other column helper in the file? The current required string name is the lone outlier — developers and AI tooling that learn the convention from t.integer(columnNames=...), t.string(columnNames=...), etc. consistently mis-call primaryKey(columnName=...) and hit "required argument missing." Same pattern that bit t.references() in #2781.

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails	name (positional) on t.primary_key(name, type, ...) — matches t.column(name, ...)	t.primary_key :order_number, :string inside create_table id: false	Consistent vocab inside TableDefinition; add_column standalone uses column_name (minor split)	Composite via primary_key: [:a, :b] option; UUID via id: :uuid
Laravel	\$column (positional) on id(), bigIncrements(), uuid() — identical to every column helper	\$table->id('user_id') — zero-arg default for 95% case	Universal \$column singular; \$columns plural only on the constraint method primary()	\$table->primary(['a','b']) for composite; id() defaults to 'id'
Django	Tuple-keyed (positional) — name is the tuple's first element, never a kwarg	("book_id", models.BigAutoField(primary_key=True))	One uniform mechanism for every column incl. PK; PK identified by scanning for primary_key=True flag	Composite via CompositePrimaryKey (5.2+); db_column= decouples attr vs DB name
Phoenix/Ecto	column (positional atom) on add/3 — uniform across all columns; PK is just primary_key: true opt	add :id, :binary_id, primary_key: true	Single add macro for everything; no special PK DSL form	table("t", primary_key: false) to suppress default; composite via multiple primary_key: true
Knex.js (+1, justified below)	TS types use columnName; docs prose says name — minor inconsistency	table.increments('id') or table.uuid('id').primary()	Two primary() overloads (column-level no-arg vs table-level array columnNames) read naturally	Composite via table.primary(['a','b']); constraintName option
Doctrine DBAL	Split: addColumn(\$name, ...) but setPrimaryKey(\$columnNames) — column creation vs constraint declaration	\$table->addColumn('id', 'integer', [...]); \$table->setPrimaryKey(['id']);	Constraint-declaring methods get plural \$columnNames; column creation gets singular \$name — deliberate split, but the PK column name is repeated twice	Composite is the default shape via array

Why Knex.js as the +1: Knex is the closest analog to Wheels' migrator — a code-first schema-builder DSL with method-chained column helpers, not a declarative model-first system like Django/Ecto. Its TS-vs-docs split (columnName vs name) is exactly the kind of inconsistency #2803 wants to fix in Wheels.

Dominant pattern

Every framework except Doctrine uses a single, uniform argument name across all column helpers including the primary-key helper. Rails uses name everywhere in TableDefinition; Laravel uses \$column everywhere; Django uses tuple-keyed positional everywhere; Ecto uses column everywhere; Knex.js uses columnName everywhere (in its TS types). The one framework that splits — Doctrine — splits along a meaningful axis: addColumn(\$name) for column creation vs setPrimaryKey(\$columnNames) for constraint declaration. That distinction doesn't apply to Wheels: TableDefinition.primaryKey() is a column-creating method (it builds a ColumnDefinition, appends to this.primaryKeys, sets type/limit/etc.) — not a constraint-declaration method. So the dominant pattern argues for aligning primaryKey's column-name argument with the rest of the file.

Recommended path for Wheels

The issue's suggested fix is correct and mirrors the prior-art from #2781 (t.references()). Add columnName/columnNames aliases via \$combineArguments, keep name working for backward compat. Body stays unchanged because all aliases resolve to arguments.name internally.

```cfm
public any function primaryKey(
string name,
string columnName,
string columnNames,
string type = "integer",
boolean autoIncrement = "false",
numeric limit,
numeric precision,
numeric scale,
string references,
string onUpdate = "",
string onDelete = ""
) {
// Accept columnName as singular alias for name
$combineArguments(args = arguments, combine = "name,columnName", required = false);
// Accept columnNames as plural alias for name (developer muscle memory from sibling helpers)
$combineArguments(args = arguments, combine = "name,columnNames", required = true);

arguments.allowNull = false;
arguments.adapter = this.adapter;
// ... rest of body unchanged — arguments.name still drives everything

}
```

Usage examples:

```cfm
// Legacy (still works)
t.primaryKey(name="userId", type="integer", autoIncrement=true);

// Modern singular convention (matches t.integer, t.string, etc.)
t.primaryKey(columnName="userId", type="integer", autoIncrement=true);

// Modern plural convention (developer muscle memory — PK is inherently single, but
// accepting this lowers the cognitive load when bouncing between column types)
t.primaryKey(columnNames="userId", type="integer", autoIncrement=true);
```

Lives in: `vendor/wheels/migrator/TableDefinition.cfc` (existing file, line 34).
Composes with: existing `$combineArguments` helper already used by all sibling column helpers; no new infrastructure.

Cross-engine notes

Clean. `$combineArguments` is already used pervasively in `TableDefinition.cfc` and works identically on Lucee 5/6/7, Adobe CF 2018–2025, and BoxLang. No closures, no struct member functions, no `application`-scope writes, no reserved scope names introduced. The new `columnName`/`columnNames` parameters are plain optional strings — no engine differences in argument resolution.

Open questions

• Should the migration generator (`wheels generate migration` / `dbmigrate diff`) emit `columnName=` for new `primaryKey()` calls going forward? Low-stakes — the legacy `name=` form keeps working — but generated code is the most visible style signal and a follow-up worth scoping if this lands.
• Should `t.references()` (Migrator: t.references() API quirks — 'referenceNames' (not 'columnNames'), and produces '<x>id' without underscore #2781) and `t.primaryKey()` (Migrator: primaryKey(name=...) is an argument-naming outlier #2803) ship in the same PR or be sequential? They're independent but share the same `$combineArguments` pattern; one PR with both feels cleaner. Probably for the implementer to decide.

Confidence: `high`

The dominant pattern is unambiguous (column-helper argument names should be uniform within a single DSL), the Wheels fix is a verbatim re-application of the #2781 pattern, no cross-engine concerns surfaced, and no Wheels anti-patterns are triggered.

Sources

• https://guides.rubyonrails.org/active_record_migrations.html
• https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html
• https://laravel.com/docs/migrations
• https://github.com/laravel/framework/blob/master/src/Illuminate/Database/Schema/Blueprint.php
• https://docs.djangoproject.com/en/stable/ref/models/fields/
• https://docs.djangoproject.com/en/stable/ref/migration-operations/
• https://hexdocs.pm/ecto_sql/Ecto.Migration.html
• https://knexjs.org/guide/schema-builder.html
• https://github.com/knex/knex/blob/master/types/index.d.ts
• https://github.com/doctrine/dbal/blob/4.5.x/src/Schema/Table.php

[wheels-bot]

Wheels Bot — Fix on hold for human review

The proposed fix touches a sensitive area (vendor/wheels/migrator/**) and the bot's safety net requires a human in the loop before any code is written.