如何定义支持2D和3D的SQLAlchemy Geometry列并适配Alembic？

阿华AIGC实验室

2026-6-12

解决SQLAlchemy+Alembic中PostGIS列兼容2D/3D几何数据的问题

问题场景

需要定义一个PostGIS Geometry列，同时支持存储2D（如POINT、LINESTRING）和3D（如POINT Z、LINESTRING Z）几何数据。现有模型配置中设置了dimension=None，但生成的数据库列仍带有2D限制，插入3D数据时报错；手动修改列后，Alembic自动迁移又会生成还原脚本，破坏3D支持。

现有模型定义

from sqlalchemy import Column
from geoalchemy2 import Geometry

geometry = Column(
    Geometry(
        geometry_type='GEOMETRY',
        dimension=None,
        srid=4326,
        spatial_index=True
    ),
    nullable=True
)

报错信息

插入3D数据时触发：

sqlalchemy.exc.DBAPIError: (sqlalchemy.dialects.postgresql.asyncpg.Error)
<class 'asyncpg.exceptions.InvalidParameterValueError'>:
Geometry has Z dimension but column does not
[SQL: INSERT INTO entity_location (entity_id, updated_at, report_datetime, location, geometry, fields)
VALUES ($1::INTEGER, $2::TIMESTAMP WITH TIME ZONE, $3::TIMESTAMP WITH TIME ZONE,
ST_GeomFromEWKT($4), ST_GeomFromEWKT($5), $6::JSONB)
RETURNING entity_location.id]
[parameters: (23, datetime.datetime(2025, 10, 11, 8, 51, 24, 659643, tzinfo=datetime.timezone.utc),
datetime.datetime(2025, 10, 8, 10, 59, 23, 295000, tzinfo=TzInfo(UTC)),
None, 'SRID=4326;POINT Z (77.5946 12.9716 920.5)',
'{"speed_kmph": 64.2, "fuel_level_percent": 73, "engine_status": "on", "temperature_c": 36.8}')]

数据库元数据验证

执行查询：

SELECT f_geometry_column, coord_dimension, srid, type
FROM geometry_columns
WHERE f_table_name IN ('entity');

结果显示列被限制为2D：

f_geometry_column	coord_dimension	srid	type
geometry	2	4326	GEOMETRY

解决方案

1. 修正SQLAlchemy模型配置

问题根源在于GeoAlchemy2默认使用typmod限制列的维度，即使设置dimension=None也会默认生成2D列。需添加use_typmod=False参数，创建无维度限制的geometry列，同时明确支持3D维度：

from sqlalchemy import Column
from geoalchemy2 import Geometry

geometry = Column(
    Geometry(
        geometry_type='GEOMETRY',
        dimension=3,  # 明确支持3D，同时兼容2D数据
        srid=4326,
        spatial_index=True,
        use_typmod=False  # 禁用typmod，创建无维度限制的geometry列
    ),
    nullable=True
)

重新生成迁移脚本后，数据库列将支持任意2D/3D几何类型，无需手动修改。

2. 阻止Alembic误检测变更

如果已经手动修改过列，或需要确保Alembic自动迁移不会还原配置，可通过以下两种方式处理：

方式一：自定义类型比较函数

修改Alembic的env.py文件，添加自定义类型比较逻辑，忽略Geometry列的维度差异：

from alembic import context
from geoalchemy2.types import Geometry

def compare_geometry_type(context, inspected_column, metadata_column, inspected_type, metadata_type):
    # 仅当geometry_type和srid不一致时，才认为类型需要变更
    if isinstance(metadata_type, Geometry) and isinstance(inspected_type, Geometry):
        return (
            metadata_type.geometry_type != inspected_type.geometry_type
            or metadata_type.srid != inspected_type.srid
        )
    return None

def run_migrations_online():
    # 保留原有配置，添加compare_type参数
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            compare_type=compare_geometry_type,  # 启用自定义比较逻辑
            # 其他原有配置...
        )

        with context.begin_transaction():
            context.run_migrations()