@warlock.js/cascade 5.8.0 → 5.9.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `@warlock.js/cascade` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.9.0 - 2026-09-13
+
+_Released in lockstep with the `@warlock.js/*` family; no package-specific changes in 5.9.0._
+
+## 5.8.0 - 2026-09-13
+
+### Added
+
+- `Migration.foreignId(name)` derives a foreign-key column's type from `migrationDefaults.primaryKey`, so FK columns match the app's chosen primary-key type (integer / bigInteger / uuid).
+
+### Fixed
+
+- Numeric-looking Postgres connection config (e.g. a numeric `DB_NAME`) is coerced to a string via `buildPostgresPoolConfig`, instead of crashing the driver with an inscrutable buffer error.
+
 ## 5.7.0 - 2026-09-11
 
 ### Fixed

package/llms-full.txt

@@ -2771,6 +2771,35 @@ export default class BackfillStatuses extends Migration {
 
 Class-form builders include `createTable()` / `createTableIfNotExists()`, `dropTable()` / `dropTableIfExists()`, `dropColumn(name)`, `renameTableTo(name)`, `timestamps()`, `index(...)`, `primaryUuid()`, and `raw(sql)` for a raw statement.
 
+### Foreign-key columns that match the app's PK type — `this.foreignId`
+
+`this.foreignId(name)` (5.8+) derives the column's type from `migrationDefaults.primaryKey` so a foreign-key column always matches the type of the `id` it points at, instead of hardcoding one:
+
+| `migrationDefaults.primaryKey` | `foreignId` produces |
+| --- | --- |
+| `uuid` | `uuid` column |
+| `bigInt` | `bigInteger` column |
+| anything else (default) | `integer` column |
+
+```ts
+import { Migration } from "@warlock.js/cascade";
+
+export default class AddUserToPosts extends Migration {
+  public readonly table = "posts";
+
+  public async up(): Promise<void> {
+    // uuid / bigInteger / integer, matching the app's chosen PK type
+    this.foreignId("user_id").index();
+  }
+
+  public down(): void {
+    this.dropColumn("user_id");
+  }
+}
+```
+
+Reach for it on plain (non-`.references()`) FK id columns — e.g. a polymorphic `user_id` paired with a `user_type` — so a reference to a default-PK model is always type-compatible with that model's `id`.
+
 ## Raw SQL migrations
 
 For SQL-only changes (Postgres), `Migration.rawSql` builds a migration class for you:

package/package.json

@@ -13,9 +13,9 @@
     "@mongez/events": "^2.2.7",
     "@mongez/reinforcements": "^4.0.1",
     "@mongez/supportive-is": "^2.1.4",
-    "@warlock.js/context": "5.8.0",
-    "@warlock.js/logger": "5.8.0",
-    "@warlock.js/seal": "5.8.0",
+    "@warlock.js/context": "5.9.0",
+    "@warlock.js/logger": "5.9.0",
+    "@warlock.js/seal": "5.9.0",
     "citty": "^0.2.2",
     "fast-glob": "^3.3.3"
   },
@@ -43,7 +43,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/write-migration/SKILL.md

@@ -124,6 +124,35 @@ export default class BackfillStatuses extends Migration {
 
 Class-form builders include `createTable()` / `createTableIfNotExists()`, `dropTable()` / `dropTableIfExists()`, `dropColumn(name)`, `renameTableTo(name)`, `timestamps()`, `index(...)`, `primaryUuid()`, and `raw(sql)` for a raw statement.
 
+### Foreign-key columns that match the app's PK type — `this.foreignId`
+
+`this.foreignId(name)` (5.8+) derives the column's type from `migrationDefaults.primaryKey` so a foreign-key column always matches the type of the `id` it points at, instead of hardcoding one:
+
+| `migrationDefaults.primaryKey` | `foreignId` produces |
+| --- | --- |
+| `uuid` | `uuid` column |
+| `bigInt` | `bigInteger` column |
+| anything else (default) | `integer` column |
+
+```ts
+import { Migration } from "@warlock.js/cascade";
+
+export default class AddUserToPosts extends Migration {
+  public readonly table = "posts";
+
+  public async up(): Promise<void> {
+    // uuid / bigInteger / integer, matching the app's chosen PK type
+    this.foreignId("user_id").index();
+  }
+
+  public down(): void {
+    this.dropColumn("user_id");
+  }
+}
+```
+
+Reach for it on plain (non-`.references()`) FK id columns — e.g. a polymorphic `user_id` paired with a `user_type` — so a reference to a default-PK model is always type-compatible with that model's `id`.
+
 ## Raw SQL migrations
 
 For SQL-only changes (Postgres), `Migration.rawSql` builds a migration class for you: