GeoAlchemy 2 Documentation

Using SQLAlchemy with Spatial Databases.

GeoAlchemy 2 provides extensions to SQLAlchemy for working with spatial databases.

GeoAlchemy 2 focuses on PostGIS. PostGIS 2 and PostGIS 3 are supported.

GeoAlchemy 2 also supports the following dialects:

• SpatiaLite >= 4.3.0 (except for alembic helpers that require SpatiaLite >= 5)

• MySQL >= 8

• MariaDB >= 5.3.3 (experimental)

• GeoPackage

Note that using GeoAlchemy 2 with these dialects may require some specific configuration on the application side. It also may not be optimal for performance.

GeoAlchemy 2 aims to be simpler than its predecessor, GeoAlchemy. Simpler to use, and simpler to maintain.

The current version of this documentation applies to the version 0.16.1.dev1+gc581698 of GeoAlchemy 2. See the GeoAlchemy 2 Changelog page for details on recent changes.

Requirements

GeoAlchemy 2 requires SQLAlchemy >= 1.4.

Installation

GeoAlchemy 2 is available on the Python Package Index. So it can be installed with the standard pip or easy_install tools.

What’s New in GeoAlchemy 2

• GeoAlchemy 2 supports PostGIS’ geometry type, as well as the geography and raster types.

• The first series had its own namespace for spatial functions. With GeoAlchemy 2, spatial functions are called like any other SQLAlchemy function, using func, which is SQLAlchemy’s standard way of calling SQL functions.

• GeoAlchemy 2 works with SQLAlchemy’s ORM, as well as with SQLAlchemy’s SQL Expression Language (a.k.a the SQLAlchemy Core). (This is thanks to SQLAlchemy’s new type-level comparator system.)

• GeoAlchemy 2 supports reflection of geometry and geography columns.

• GeoAlchemy 2 adds to_shape, from_shape functions for a better integration with Shapely.

See the Migrate to GeoAlchemy 2 page for details on how to migrate a GeoAlchemy application to GeoAlchemy 2.

Tutorials

GeoAlchemy 2 works with both SQLAlchemy’s Object Relational Mapping (ORM) and SQL Expression Language. This documentation provides a tutorial for each system. If you’re new to GeoAlchemy 2 start with this.

• ORM Tutorial
• Core Tutorial
• SpatiaLite Tutorial

Gallery

The Gallery page shows examples of the GeoAlchemy 2’s functionalities.

Use with Alembic

The GeoAlchemy 2 package is compatible with the migration tool Alembic. The Use Alembic with GeoAlchemy 2 page provides more details on this topic.

Reference Documentation

• Administration
• Types
• Elements
• Spatial Functions
• Spatial Operators
• Shapely Integration
• Alembic helpers

Development

The code is available on GitHub: https://github.com/geoalchemy/geoalchemy2.

Contributors:

• Adrien Berchet (https://github.com/adrien-berchet)

• Éric Lemoine (https://github.com/elemoine)

• Dolf Andringa (https://github.com/dolfandringa)

• Frédéric Junod, Camptocamp SA (https://github.com/fredj)

• ijl (https://github.com/ijl)

• Loïc Gasser (https://github.com/loicgasser)

• Marcel Radischat (https://github.com/quiqua)

• Matt Broadway (https://github.com/mbway)

• rapto (https://github.com/rapto)

• Serge Bouchut (https://github.com/SergeBouchut)

• Tobias Bieniek (https://github.com/Turbo87)

• Tom Payne (https://github.com/twpayne)

Many thanks to Mike Bayer for his guidance and support! He also fostered the birth of GeoAlchemy 2.

Citation

When you use this software, we kindly ask you to cite the following DOI:

Indices and tables

• Index

• Module Index

• Search Page