Add spatial types #7096

ddegasperi · 2025-08-18T07:53:36Z

Q	A
Type	feature
Fixed issues	#7081

Summary

This PR introduces spatial data type support for DBAL, starting with PostgreSQL/PostGIS and MySQL. This implementation is intended to serve as a reference and guide for adding support for other database platforms in the future.

Core Spatial Types

GeometryType (Types::GEOMETRY) - For planar coordinate systems
GeographyType (Types::GEOGRAPHY) - For spherical earth coordinates
Both types handle GeoJSON format for data exchange

Schema API Integration

Extended Column and ColumnEditor with geometryType and srid properties
Clean fluent API: Column::editor()->setGeometryType('POINT')->setSrid(4326)
Full PostgreSQL platform support with PostGIS-specific SQL generation
Schema introspection and table creation/modification support

What's next

Discuss the PR
Add other platforms (PostgreSQL/PostGIS, MySQL)
Add spatial index (PostgreSQL/PostGIS, MySQL already support creation of spatial indexes)

derrabus · 2025-08-18T08:06:54Z

tests/Platforms/PostgreSQLPlatformTest.php

+        self::assertSame(
+            [
+                'CREATE TABLE spatial_table (id INT NOT NULL, '
+                . 'location geometry(geometry) NOT NULL, '
+                . 'point_location geometry(point,4326) NOT NULL, '
+                . 'polygon_area geometry(polygon) NOT NULL)',
+            ],
+            $this->platform->getCreateTableSQL($table),
+        );


Please focus on functional tests. The kind of test that you're building here is pretty much worthless because it does not tell us if the SQL actually works when it hits a database.

Thanks for the feedback! I already had in mind to add functional tests, since they’re definitely the right way to validate the SQL.
Because these tests require PostgreSQL with the PostGIS extension, would you suggest:

creating a dedicated GitHub workflow (e.g. postgresql-postgis.yml) that uses the postgis/postgis image, or

replacing the current PostgreSQL workflow with that image so that all PostgreSQL jobs run with PostGIS enabled?

I’d be happy to go with whichever approach best fits the project’s CI strategy.

We need to make sure DBAL still works with Postgres databases that don't have these extensions installed. So it's probably best for now if we add an additional check for Postgres that uses the latest postgis image and leave the other checks as they are.

@derrabus I’ve added the functional tests as suggested and pushed them. However, I noticed that none of the functional tests actually executed in the PR pipeline — is there something I need to do to make sure they run?

If you already had a chance to take a look, I’d really appreciate some feedback on whether this is heading in the right direction. That way I can adjust before proceeding with support for a second platform (e.g. MySQL).

As far as I can tell, your new workflows were run: https://github.com/doctrine/dbal/actions/runs/17288021054/job/49069200071?pr=7096

Yes, I noticed an error in continuous-integration.yml only afterwards. After fixing it, the functional tests were executed correctly.

I have one question regarding the functional tests: in MySQL there is a test case Doctrine\DBAL\Tests\Functional\Schema\MySQLSchemaManagerTest::testColumnIntrospection that attempts to define any type as a column to compare it against the same definition. At the moment, I’ve introduced two types for PostgreSQL/PostGIS, geometry and geography. Since geography is not available in MySQL, the current test setup would fail.

Is this behavior intentional, or would it be acceptable to adjust the tests so that they explicitly check which types are supported on MySQL?

derrabus · 2025-09-04T21:34:20Z

src/Types/GeometryType.php

+        if (is_string($value)) {
+            return $value;
+        }


Is there any object representation that we could hydrate this value to? If we just pass on the strings we might end up with a leaky abstraction.

Good point — I agree that passing raw strings would be a leaky abstraction. Since the implementation uses WKT, I could introduce a lightweight WKT value object that wraps and optionally validates the string (e.g. via regexp). This would give us a clear object representation without pulling in a full geometry library. Would this be in line with what you had in mind?

I decided not to introduce a WKT value object and went with a GeoJSON value object instead. GeoJSON provides both the geometry and its metadata (such as SRID) in a consistent way across different database platforms.

tibobaldwin · 2025-09-06T09:41:46Z

Adding spatial index management would be interesting for this PR I think :).

For instance:
CREATE INDEX mytable_geom_x ON mytable USING GIST (geom)

Sources:

ddegasperi · 2025-09-08T06:39:41Z

Adding spatial index management would be interesting

Thanks for the advice — I agree, index management is definitely an important aspect when working with geometry data. I haven’t investigated it in depth yet, but it looks like this might already be supported by specifying the index type. A quick search in the repository shows an IndexType enum with a SPATIAL option, so I’ll take a closer look at how that could be integrated here.

Add geometry and geography types for spatial data Introduces new spatial data types for handling geometric and geographic data in database applications. GeometryType handles planar coordinates while GeographyType handles spherical earth coordinates, both using GeoJSON format. This provides foundation for spatial data operations across database platforms that support spatial extensions.

Extends Column and ColumnEditor with geometryType and srid properties to support PostgreSQL's PostGIS spatial types and provides a clean schema API for working with GEOMETRY and GEOGRAPHY columns while maintaining backward compatibility. This builds on the core spatial types implementation to complete the PostgreSQL spatial type support at the schema level.

This commit adds functional testing for PostGIS spatial types (GEOMETRY and GEOGRAPHY) with schema introspection and CI integration. The implementation leverages PostgreSQL's native type system for introspection, making it compatible with any PostgreSQL instance without requiring PostGIS system tables to be accessible during schema operations.

Extends AbstractMySQLPlatform with GEOMETRY type support and enhances MySQLSchemaManager to introspect spatial columns with geometryType and SRID properties. MySQL supports GEOMETRY types (POINT, LINESTRING, POLYGON, etc.) with optional SRID constraints using the conditional comment syntax for MySQL 8.0.3+.

Refactor GeometryType and GeographyType to replace direct GeoJSON string handling with dedicated value objects, preventing exposure of database-specific formats to application code. This commit introduces a Geometry value object that encapsulates a supporting GeoJSON value object responsible for validating and wrapping GeoJSON representations.

Implement spatial index creation and introspection for PostgreSQL using the GIST (Generalized Search Tree) index method — the standard access method for spatial data in PostGIS. This commit introduces a new getIndexMethodSQL() hook in AbstractPlatform for platform-specific index clauses, and overrides it in PostgreSQLPlatform to emit "USING GIST" for spatial indexes. SQL generation examples: MySQL → CREATE SPATIAL INDEX idx ON table (col) PostgreSQL → CREATE INDEX idx ON table USING GIST (col)

derrabus reviewed Aug 18, 2025

View reviewed changes

ddegasperi force-pushed the add-spatial-types branch from 543f582 to a35520d Compare August 19, 2025 11:46

greg0ire marked this pull request as draft August 26, 2025 14:16

ddegasperi force-pushed the add-spatial-types branch 3 times, most recently from 810f526 to 86b4b15 Compare August 28, 2025 06:44

derrabus reviewed Sep 4, 2025

View reviewed changes

ddegasperi force-pushed the add-spatial-types branch 2 times, most recently from ba2a7aa to a33fcd8 Compare October 10, 2025 13:06

ddegasperi force-pushed the add-spatial-types branch 3 times, most recently from 21795c6 to bc5c9db Compare October 14, 2025 14:43

ddegasperi added 3 commits October 14, 2025 16:49

ddegasperi force-pushed the add-spatial-types branch from bc5c9db to 0b81371 Compare October 14, 2025 14:50

ddegasperi added 3 commits October 14, 2025 17:24

ddegasperi force-pushed the add-spatial-types branch from 0b81371 to a3544b1 Compare October 14, 2025 15:24

ddegasperi changed the title ~~[DRAFT] Add spatial types~~ Add spatial types Oct 14, 2025

ddegasperi marked this pull request as ready for review October 14, 2025 15:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add spatial types #7096

Add spatial types #7096

ddegasperi commented Aug 18, 2025 •

edited

Loading

Uh oh!

derrabus Aug 18, 2025

Uh oh!

ddegasperi Aug 18, 2025

Uh oh!

derrabus Aug 18, 2025

Uh oh!

ddegasperi Aug 25, 2025

Uh oh!

derrabus Sep 4, 2025

Uh oh!

ddegasperi Sep 8, 2025

Uh oh!

derrabus Sep 4, 2025

Uh oh!

ddegasperi Sep 8, 2025

Uh oh!

ddegasperi Oct 14, 2025

Uh oh!

tibobaldwin commented Sep 6, 2025 •

edited

Loading

Uh oh!

ddegasperi commented Sep 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Add spatial types #7096

Are you sure you want to change the base?

Add spatial types #7096

Conversation

ddegasperi commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Core Spatial Types

Schema API Integration

What's next

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tibobaldwin commented Sep 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ddegasperi commented Sep 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ddegasperi commented Aug 18, 2025 •

edited

Loading

tibobaldwin commented Sep 6, 2025 •

edited

Loading