Alembic autogenerate fails with KeyError: 'name' due to missing constraint metadata

[jlynchMicron]

AI generated bug ticket (but confirmed by me)

When running alembic revision --autogenerate against a BigQuery‑backed SQLAlchemy metadata model, the autogenerate process crashes with:

KeyError: 'name'

The error originates inside Alembic’s constraint‑reflection normalization (_apply_reflectinfo_conv), which unconditionally accesses const["name"]. The BigQuery dialect returns constraint dictionaries without a 'name' field, causing Alembic to fail during autogenerate.

This makes Alembic migrations unusable for any project that uses SQLAlchemy + BigQuery + autogenerate.

---

Environment

• Python: 3.11
• SQLAlchemy: 2.0.46
• Alembic: 1.18.2
• sqlalchemy-bigquery: 1.16.0
• Backend: Google BigQuery
• ORM style: Imperative mapping with polymorphic inheritance

---

Error details

Traceback excerpt

File ".../alembic/autogenerate/compare/util.py", line 259, in _apply_reflectinfo_conv
    if const["name"] is not None and not isinstance(
KeyError: 'name'

What triggers it

• Alembic reflects constraints (PKs, UNIQUE, FKs, CHECK, etc.)
• BigQuery dialect’s implementation of:
  • Inspector.get_pk_constraint()
  • Inspector.get_unique_constraints()
  • (and potentially others)

returns dictionaries that omit mandatory keys, especially 'name'.

Alembic expects at minimum:

{
    "name": <str or None>,
    "constrained_columns": [...],
}

but BigQuery returns incomplete structures.

---

Related existing issue(s)

This appears closely related to (but not identical to):

• sqlalchemy inspect constraints support #866 — “sqlalchemy inspect constraints support”
  That issue documents that constraint reflection is not implemented, and get_pk_constraint() / get_foreign_keys() return empty or incomplete structures.
  This missing data directly causes Alembic to crash during autogenerate.

However, there is currently no issue specifically tracking Alembic autogenerate failures caused by missing 'name' in reflected constraint dictionaries, so filing this as a distinct bug.

---

Expected behavior

Alembic autogenerate should:

• Successfully compare ORM metadata vs. reflected DB state
• Not crash due to missing fields
• Treat missing constraint information as either:
  • empty constraints
  • or unsupported constraint types

The dialect should implement constraint reflection methods that meet SQLAlchemy’s expected return formats.

---

Actual behavior

• Constraint dictionaries returned by the BigQuery dialect lack required fields, e.g. 'name'
• Alembic crashes during its normalization phase
• --autogenerate cannot be used at all for BigQuery projects

---

Minimal reproduction

1. Define any model with a primary key in SQLAlchemy.
2. Point engine at BigQuery using sqlalchemy-bigquery.
3. Run:

   alembic revision --autogenerate -m "test"

4. Autogenerate fails with KeyError: 'name'.

No foreign keys or unique constraints are required — even a simple PK is enough.

---

Why this matters

Alembic autogenerate is standard tooling for SQLAlchemy projects. BigQuery is increasingly used with SQLAlchemy (especially for ETL / analytics pipelines). Without correct constraint reflection, migrations cannot be generated at all.

This blocks:

• new project bootstrapping
• schema evolution workflows
• compatibility with SQLAlchemy 2.x and Alembic 1.7+

---

Proposed solutions

Short term

Ensure dialect’s Inspector methods always return dictionaries with the keys Alembic expects:

• For PKs:

  {"name": None, "constrained_columns": [...]}

• For UNIQUE constraints:

  {"name": None, "column_names": [...]}

Even if BigQuery does not enforce constraints, returning a complete dict prevents Alembic from crashing.

Long term

Implement actual constraint reflection using BigQuery’s INFORMATION_SCHEMA.TABLE_CONSTRAINTS and related views.

---

Workaround

Users can monkey‑patch Inspector methods in env.py to inject 'name' fields, but this is brittle and clearly not the intended solution.

---

Request

Please add proper constraint reflection to the dialect, or at least ensure that Inspector methods return dictionaries compatible with Alembic expectations so that autogenerate no longer fails.

Happy to provide a PR or deeper reproducer if helpful.

[jlynchMicron]

I guess I should also mention that I know BQ does not support true PK/FK relational constrains, but I still define them anyways for auto generated join conditions using a SQLalchemy ORM.