Wheels migration with foreign key fails on Linux. No function with name addForeignKeyOptions

[teleotic]

Describe the bug
Wheels migration command fails when running a migration involving foreign key definitions. Running wheels migrate latest results in an error:

Running migration: latest...
Migrating from 0 up to 20260605110522.

-------- 20260605110522_create_products_table --------------
Error migrating to 20260605110522.
Component [wheels.databaseAdapters.PostgreSQL.PostgreSQLMigrator] has no function with name [addForeignKeyOptions]

To Reproduce
Steps to reproduce the behavior:

1. wheels new test_app
2. cd test_app
3. wheels generate scaffold Post title body:text publishedAt:datetime --belongsTo=author
4. wheels migrate latest
5. See error

Expected behavior
Successful migration with creation of database table including a foreign key column.

Desktop

• OS: Ubuntu 26.04 LTS
• 4.0.2, 4.0.3-snapshot.1991 (bleeding-edge),

Additional context
Ran into this error with a more complicated model. This was the most direct reproduction method I found.

Error does NOT occur on Windows, with the same Wheels version.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes a concrete failure with a clear error message — Component [wheels.databaseAdapters.PostgreSQL.PostgreSQLMigrator] has no function with name [addForeignKeyOptions] — and clean reproduction steps (wheels new → scaffold with --belongsTo → wheels migrate latest).

Suspected layer

migrator — see .ai/wheels/migrator/ and vendor/wheels/databaseAdapters/ for canonical patterns.

Fix sketch

vendor/wheels/databaseAdapters/PostgreSQL/PostgreSQLMigrator.cfc is missing the addForeignKeyOptions(sql, options) public method that every other adapter implements (MySQLMigrator.cfc:27, SQLiteMigrator.cfc:31, MicrosoftSQLServerMigrator.cfc:23, OracleMigrator.cfc:220). vendor/wheels/migrator/ForeignKeyDefinition.cfc:57 calls this.adapter.addForeignKeyOptions(...) unconditionally when emitting FK DDL, so any belongsTo scaffold on Postgres throws. The fix is mechanical: add the method, mirroring MySQL's signature (FOREIGN KEY (col) REFERENCES tbl (refCol)), but using PostgreSQL identifier quoting via the adapter's quoteTableName / quoteColumnName. The "works on Windows" note in the report is almost certainly because the Windows reproduction used the default SQLite datasource (which has the method); the bug is OS-independent and Postgres-specific.

Confidence: medium

Layer and target file are unambiguous (the engine names them in the error), and a sibling adapter provides a near-copy template — but the auto-downgrade rule for migrator/DDL-emitting code applies, and PostgreSQL FK syntax warrants a quick cross-check against the project's existing FK tests before landing.

<!-- wheels-bot:triage:2876 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[teleotic]

Looking at the error closely -- I am using PostgreSQL on my other project, but the test_app should have generated a SQLite database by default.

This may relate to the Windows test not showing the same error.

[teleotic]

Because I had not shut down my other project's Lucee server, it seems that server ran the test_app's migration script. This would appear to be an additional bug, which I will file separately.

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2877

Spec: vendor/wheels/tests/specs/migrator/postgreSQLForeignKeyOptionsSpec.cfc — failing (Component [wheels.databaseAdapters.PostgreSQL.PostgreSQLMigrator] has no function with name [addForeignKeyOptions], matching the issue body) → passing
Implementation: vendor/wheels/databaseAdapters/PostgreSQL/PostgreSQLMigrator.cfc (adds the missing addForeignKeyOptions(sql, options), mirroring the MySQL signature; CockroachDB inherits the fix via its PG subclass)

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.