Skip to content

Feat: Respect naming conventions for autogenerated spatial indexes - #628

Open
adrien-berchet wants to merge 3 commits into
geoalchemy:mainfrom
adrien-berchet:naming_convention
Open

adrien-berchet wants to merge 3 commits into
geoalchemy:mainfrom
adrien-berchet:naming_convention

Conversation

@adrien-berchet

Copy link
Copy Markdown
Member

Summary

Closes #401.

This PR adds an opt-in parameter, follow_naming_convention (default False), to Geometry, Geography, and Raster types. When enabled, autogenerated spatial indexes follow the naming conventions defined on SQLAlchemy's MetaData(naming_convention=...) instead of being hardcoded to idx_<tablename>_<columnname>.

Context & Motivation

Previously, GeoAlchemy2 always generated spatial index names via the internal helper _spatial_idx_name(table.name, column.name), which hardcoded the format idx_<tablename>_<columnname>. This ignored any custom naming conventions configured on MetaData.naming_convention (or SQLAlchemy's default convention {"ix": "ix_%(column_0_label)s"}), causing inconsistency across schemas and false diffs during Alembic autogenerate migrations.

Key Changes

1. Opt-In Parameter & Fallback Resolution

  • Added follow_naming_convention: bool = False to _GISType (Geometry, Geography) and Raster.
  • When follow_naming_convention=True, an unnamed Index(None, ...) is appended to the table during before_parent_attach, allowing SQLAlchemy to resolve the name against MetaData.naming_convention["ix"].
  • If the metadata does not define an "ix" (or Index) naming convention key, the index name safely falls back to idx_<tablename>_<columnname>.

2. Marker-Based Index Identification

  • Replaced name-based checks (idx.name == _spatial_idx_name(...)) across all dialects with an internal marker: info={"geoalchemy2_spatial_index": True} (plus _column_flag=True).
  • Custom user indexes explicitly named idx_<tablename>_<columnname> are no longer mistaken for autogenerated spatial indexes and will no longer have their options (e.g. postgresql_where) silently dropped.

3. Dialect Support

  • PostgreSQL:
    • Unmanaged/typmod path (use_typmod=True) generates convention-named GiST indexes during table creation.
    • Managed path (use_typmod=False) stores the convention name in table.info["_generated_spatial_indexes"] so after_create creates the index with the resolved name.
  • MySQL / MariaDB:
    • Emits ALTER TABLE <table> ADD SPATIAL INDEX <format_index>(<quoted_col>) when follow_naming_convention=True.
    • Maintains legacy unnamed ALTER TABLE <table> ADD SPATIAL INDEX(<quoted_col>) when disabled.
    • Fixes reflection in _monkey_patch_get_indexes_for_mysql to only synthesize idx_t_c when INDEX_NAME == COLUMN_NAME (MySQL's default unnamed index), avoiding duplicate index diffs in Alembic for explicitly named user spatial indexes.
  • MSSQL:
    • Emits spatial index creation statements post-table creation using the resolved convention name.
    • Supports convention name resolution in alter_geo_column via target_metadata.
  • SQLite / SpatiaLite & GeoPackage:
    • SpatiaLite R-tree virtual tables (idx_<table>_<column>) and GeoPackage R-tree tables (rtree_<table>_<column>) cannot be renamed due to C-extension requirements.
    • Added Alembic rewriter logic (_filter_sqlite_spatial_index_ops via writer) to filter out false drop/create diffs when comparing models with existing databases.

4. Documentation & Migration Guide

  • Updated doc/alembic.rst with a detailed section on naming conventions, fallback rules, dialect specifics, and guidance on migrating existing databases.
  • Updated CHANGES.txt.

Backward Compatibility

  • Default behavior is 100% backward compatible: follow_naming_convention defaults to False, preserving exact previous index names (idx_<table>_<column>), DDL statements, and Alembic behavior.
  • Existing databases and migrations remain unchanged unless explicitly opting in on the type.

Verification & Testing

  • Added comprehensive unit and functional tests across all dialects:
    • tests/test_admin_common.py
    • tests/test_functional_postgresql.py
    • tests/test_functional_mysql.py
    • tests/test_functional_sqlite.py
    • tests/test_functional_geopackage.py
    • tests/test_functional_mssql.py
    • tests/test_alembic_migrations.py
  • Full test suites pass on both py312-sqlalatest and py312-sqla14 with required coverage reached (>= 89%).
  • Linters (ruff check, ruff format) pass cleanly.

…eoalchemy#401)

Add the `follow_naming_convention` parameter (default `False`) to
`Geometry`, `Geography`, and `Raster` types to allow autogenerated spatial
indexes to respect SQLAlchemy metadata naming conventions.
- Mark autogenerated indexes with `info={"geoalchemy2_spatial_index": True}`
  rather than relying on name-based checks.
- Resolve naming conventions from `MetaData.naming_convention["ix"]` with
  fallback to `idx_<table>_<column>` if no convention is set.
- Respect explicit index names in MySQL DDL when enabled while maintaining
  unnamed `ADD SPATIAL INDEX(col)` when disabled.
- Eliminate Alembic false diffs for SQLite/SpatiaLite and GeoPackage R-tree
  virtual tables via Alembic rewriters.
- Update Alembic documentation and migration test suite.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Autogeneration should respect the specified naming convention

1 participant