fix(#414, #415): PostgreSQL introspection reads spaced identifiers and con.confkey

Two defects in the PostgreSQL schema reader, both found during #389 and deferred
there with in-place comments. Landed together because they share a file, a test
surface and a verification cost.

#414 — the `columns` aggregate is `quote_ident(name) || ' ' || format_type(...)`
and the reader split it on `" "`, so an identifier CONTAINING a space was torn in
half before anything else saw it: `"Parent Id" bigint` yielded the phantom name
`"Parent` (the leading quote survives — `_unquote_ident` correctly refuses to strip
a lone unbalanced one), the non-type `Id"` so the column degraded to TextField, and
a LOST relation, because `fk_map`/`pk_set`/`index_map` all key on names that survive
a space. makemigrations then proposed adding the phantom and dropping the real
column on every run, forever. SQLite was never affected.

Fixed in the PARSER, not the aggregate: `quote_ident` output is self-delimiting, so
scanning to the closing quote recovers every name that reaches the function whole.
The flag/type scans move onto the post-name remainder in the same change, which
closes the sibling class where a column NAMED like a marker marked itself.

#415 — the `foreign_keys` CTE derived an FK's referenced column from the parent's
PRIMARY KEY INDEX; `con.confkey` was not selected anywhere in the file. An FK
pointing at a non-PK UNIQUE column reported the wrong column, and a composite
parent key fanned every aggregate out once per parent key column, so the last entry
silently won the `fk_map` assignment and the delete_rules alignment #292
established broke with it.

Now correlated through `unnest(con.conkey, con.confkey)` — bound-agnostic, so unlike
a `conkey[1]` subscript it carries none of #347's lower-bound hazard. Adds no
version floor: the `indexes` CTE in the same statement already requires PG 11+.

Three behavior changes fall out, all deliberate and documented:
  * a genuine MULTI-column FK is skipped rather than guessed at, on BOTH engines
    (PG by `array_length(con.conkey, 1) = 1`, SQLite by grouping PRAGMA
    foreign_key_list on `id`, which used to split one constraint into N relations).
    PormG has no composite-FK field type; reading one approximately would
    regenerate a different schema.
  * an FK referencing a non-PK UNIQUE column reads that column.
  * an FK whose parent has NO primary key is visible at all — the dropped
    `pg_index` join was INNER, so such a key vanished from the PG read entirely
    while SQLite reported it.

Also restores `db_column = "driver ref"` on the Odd_identifier_scratch fixture,
which #394 had to leave out precisely because of #414 — the global no-drift
assertion in test_db_table_db.jl is now the live gate for this parse. And
test_importers_introspection.jl gains the standalone guard it uniquely lacked, so
it no longer forces the full runtests.jl prologue to see one assertion.

Verification: unit 8874/8874; full SQLite integration suite 2172 pass / 1
pre-existing broken / 0 fail; db_sl introspection slice 78/78; docs build clean.
Mutation-checked — reverting the parser fails 13 assertions, removing the SQLite
skip fails 4.

NOT verified: the PostgreSQL behavior of #415. A read-only probe confirms the new
CTE parses and executes against db_2 and that none of its 28 existing FK tables
regress, but measured side by side the old and new CTE agree on all 28 — db_2
carries neither affected shape today, so that probe is a no-regression check, not
a gate. Sections 3f/3g/3h and the spaced-db_column no-drift assertion need a full
db_2 run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: PingoLee

UPGRADING.md

@@ -45,6 +45,122 @@ _Changes merged but not yet cut into a release. A consumer dev'ing PormG at HEAD
 and `PormG.upgrade_guide` surfaces them by default. When the maintainer next rolls changes into a
 consuming app, `/pormg-cut-release` stamps every entry below with `0.5.0`, dates them, and tags it._
 
+## Schema introspection reads two column shapes differently — spaced identifiers, and multi-column foreign keys (#414, #415)
+
+- **Version**: Unreleased
+- **PormG ref**: #414, #415; `src/migrations/introspection.jl`, `docs/src/schema_conventions.md`
+- **Recorded**: 2026-08-26
+- **Severity**: **behavior change (narrow — only apps whose live schema has one of these two shapes)**.
+  Nothing changes for a schema without a spaced identifier or a composite foreign key. Where one
+  exists there are **two** ways it reaches you, and the second needs no action on your part to fire:
+  a **regenerated** model file names different fields than before, **and** `makemigrations` — which
+  runs introspection on every invocation — can now start proposing a change on every run against a
+  model file you have not touched. Part of the `0.5.x` pre-publish wave.
+
+### What changed
+
+Both are corrections to what PormG **reads back** from a live database. Neither changes anything you
+declare, and neither alters your schema.
+
+**1. A column name containing a space is no longer torn in half (#414).** The PostgreSQL reader split
+its `columns` aggregate on the space between the name and the type, so an identifier that *contained*
+a space was destroyed before anything else saw it. A column named `driver ref` came back as the
+phantom `"driver` — leading quote and all — and `Parent Id` came back as `"Parent`, typed
+`TextField`, **with its foreign key dropped**, because the FK lookup keyed on the real name and no
+longer matched. `makemigrations` then proposed adding the phantom and dropping the real column on
+every run, forever. SQLite was never affected, so one schema introspected correctly on one engine and
+corruptly on the other.
+
+**2. A multi-column foreign key is now skipped rather than guessed at (#415).** PormG has no
+composite-`ForeignKey` field type. PostgreSQL used to derive the referenced column from the parent's
+*primary key index* instead of the constraint's own `confkey`, binding a composite FK to an arbitrary
+column; SQLite split it into one independent single-column relation per member. Both now import the
+member columns as **ordinary fields with no relation** and leave the constraint alone in the
+database — the same reject-rather-than-reinterpret rule that keeps a non-default index out of an
+imported model. Re-emitting either previous reading produced a *different* schema than the live one.
+
+Two more single-column cases now read **correctly** where they used to read wrong — but "correct"
+is still a *change*, so your declared model is the stale side and both need action, in the opposite
+direction from change 2:
+
+- **An FK referencing a non-primary-key `UNIQUE` column** (`REFERENCES driver_registry(licence_no)`)
+  now reports that column. The old importer wrote its wrong answer explicitly into your model file —
+  `Model_to_str` emits `pk_field=` on every introspected FK — so a model still declaring
+  `pk_field="id"` disagrees with a live read of `licence_no`, and the planner proposes `:pk_field` on
+  every run. Update the declaration to the column the constraint really names.
+- **An FK whose parent table has no primary key at all** was previously *invisible* to PostgreSQL
+  introspection (the referenced column only needs a `UNIQUE` constraint, but the old query reached it
+  through the parent's primary-key index with an inner join). Your model therefore has a plain column
+  where the live read now reports a relation. Declare the `ForeignKey`.
+
+### How to find the calls to migrate
+
+**Do not assume you are safe because you have not re-run the importer.** `makemigrations` calls the
+same introspection (`convert_schema_to_models`, `src/migrations/planner.jl`), so change 2 can bite a
+model file you never regenerate: if your model still declares `ForeignKey` on a composite-FK member
+column, the live read now says "plain integer", the declared side still says "relation",
+`describes_same_column` refuses to equate them, and the planner proposes a change **on every
+`makemigrations`** — on SQLite, a full table rebuild each time.
+
+```bash
+# 1. Which of the FOUR shapes does your schema actually have? (PostgreSQL)
+#    a. multi-column foreign keys — change 2
+psql -c "SELECT conrelid::regclass, conname FROM pg_constraint
+         WHERE contype = 'f' AND array_length(conkey, 1) > 1;"
+#    b. identifiers containing a space — change 1
+psql -c "SELECT table_name, column_name FROM information_schema.columns
+         WHERE column_name LIKE '% %';"
+#    c. foreign keys NOT pointing at the parent's primary key
+psql -c "SELECT c.conrelid::regclass, c.conname FROM pg_constraint c
+         JOIN pg_index i ON i.indrelid = c.confrelid AND i.indisprimary
+         WHERE c.contype = 'f' AND c.confkey::int[] <> i.indkey::int[];"
+#    d. foreign keys into a parent with no primary key at all
+psql -c "SELECT c.conrelid::regclass, c.conname FROM pg_constraint c
+         WHERE c.contype = 'f' AND NOT EXISTS (
+           SELECT 1 FROM pg_index i WHERE i.indrelid = c.confrelid AND i.indisprimary);"
+
+# 2. For anything those returned, grep your models for the affected columns.
+grep -n "ForeignKey" <your db_def_folder>/*.jl
+
+# 3. Then run makemigrations and read the plan BEFORE applying it. A proposal against a table you
+#    did not change is this entry — and step 3 catches all four shapes even if you skipped step 1.
+```
+
+### Migrate your app
+
+```julia
+# ── change 2: a composite-FK member column must stop declaring a relation ──
+# ✗ before — ONE constraint, `FOREIGN KEY (raceid, driverid) REFERENCES result(raceid, driverid)`,
+#   imported as two single-column relations. Note both name the SAME parent: a composite FK has one
+#   referenced table, so this is the shape to look for. Two relations pointing at DIFFERENT parents
+#   are two ordinary foreign keys, which this change does not touch — do not delete those.
+#   (The `pk_field` values below are what the old SQLite reader wrote. The old PostgreSQL reader
+#   named the parent's primary-key column on both members instead; either way, both lines go.)
+Lap_time = Models.Model("lap_time",
+  raceid   = Models.ForeignKey("result", pk_field="raceid"),
+  driverid = Models.ForeignKey("result", pk_field="driverid"),
+)
+
+# ✓ after — plain columns; the constraint stays in the database, PormG just stops modelling it.
+#   REGENERATE if you can: hand-declaring means matching the column exactly, and two attributes
+#   drift if you get them wrong. Type — introspection maps `bigint` to BigIntegerField and `integer`
+#   to IntegerField (src/constants.jl), so IntegerField() over a BIGINT column drifts on `:type`
+#   forever. And nullability — `:null` has no exemption in `_NON_SCHEMA_FIELD_ATTRS`, so a bare
+#   field declared over a NULLable column drifts on `:null` the same way.
+Lap_time = Models.Model("lap_time",
+  raceid   = Models.BigIntegerField(),
+  driverid = Models.BigIntegerField(),
+)
+
+# ── change 1: a spaced column's regenerated FIELD NAME is sanitized, and gains a db_column ──
+# ✗ before — the phantom name, truncated at the space
+M.Driver.objects.filter("driver" => "senna")
+
+# ✓ after — `Model_to_str` emits `driver_ref = CharField(db_column="driver ref", …)`,
+#           so the field is `driver_ref` and the physical column keeps its space
+M.Driver.objects.filter("driver_ref" => "senna")
+```
+
 ## `values()` refuses two projections that would render the same output name (#441)
 
 - **Version**: Unreleased

docs/src/schema_conventions.md

@@ -488,6 +488,33 @@ category = Models.ForeignKey("constructor", on_delete=CASCADE)
 | `DO_NOTHING` | `NO ACTION` |
 | `PROTECT` | `RESTRICT` |
 
+### A foreign key may reference any unique column, not only the key
+
+`pk_field` records the column the constraint actually names, which does not have to be the parent's
+primary key — referencing any column with a `UNIQUE` constraint is legal on both engines, and
+introspection reads it back as declared:
+
+```julia
+# live: parent_key VARCHAR(20) REFERENCES driver_registry(licence_no)
+#       …where driver_registry's primary key is `id` and `licence_no` is UNIQUE
+registration = Models.ForeignKey("driver_registry", pk_field="licence_no", on_delete=CASCADE)
+```
+
+!!! warning "A multi-column foreign key is not read back"
+    PormG has no composite-`ForeignKey` field type, so `FOREIGN KEY (a, b) REFERENCES parent(x, y)`
+    is **skipped** by `inspectdb`/`makemigrations` introspection on both PostgreSQL and SQLite: the
+    member columns are imported as ordinary fields with no relation, and the constraint is left
+    alone in the database.
+
+    This is deliberate — the same reject-rather-than-reinterpret rule that keeps a non-default index
+    out of an imported model. The alternatives both regenerate a *different* schema: bind to one
+    arbitrary member column, or emit one single-column constraint per member, which the parent will
+    usually refuse because no member is unique on its own. Being skipped means the column reads as
+    "no relation" on both sides of the diff, so a re-diff proposes nothing rather than churning.
+
+    A **single**-column foreign key into a composite-keyed parent is unaffected and reads back
+    normally — it names one column, and that column carries its own `UNIQUE`.
+
 ## Timestamp fields
 
 PormG does **not** implicitly add `created` / `modified` columns. Auto-managed timestamps are