googleapis / googleapis/google-cloud-python
Alembic autogenerate fails with KeyError: 'name' due to missing constraint metadata
- Dominant language
- Python
- Stars
- 5.4k
- Forks
- 1.8k
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 122
Description
#### 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:
```python
{
"name": ,
"constrained_columns": [...],
}
```
but BigQuery returns incomplete structures.
***
## **Related existing issue(s)**
This appears closely related to (but not identical to):
* **#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:
```bash
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:
```python
{"name": None, "constrained_columns": [...]}
```
* For UNIQUE constraints:
```python
{"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.
Contributor guide
Assessment
This issue has not been assessed yet.