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?

src/Types/GeometryType.php

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.

jungleman12 · 2025-11-16T16:45:50Z

Wow, that's exactly what I'd like to see integrated into Doctrine soon. Great work!

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)

ddegasperi · 2025-12-05T15:02:26Z

Hi @derrabus

I’ve addressed all the feedback received so far and updated the PR accordingly.
When you get a chance, could you please let me know if there’s anything else I can do to help move this forward?

Thanks a lot for your time

derrabus

Thank your for all the work you've put into this PR. Your changes look very promising.

derrabus · 2025-12-10T09:21:35Z

.github/workflows/continuous-integration.yml

+          - "8.3"
+          - "8.4"


Suggested change

- "8.3"

- "8.4"

- "8.5"

I don't expect any new insights from testing on multiple PHP versions, do you? Let's not bloat the matrix too much. Let's test with the lastest PHP version on both extensions and on the lowest supported PHP version with one extension only.

derrabus · 2025-12-10T09:22:42Z

.github/workflows/phpunit-postgis.yml

+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4


Suggested change

uses: actions/checkout@v4

uses: actions/checkout@v6

derrabus · 2025-12-10T09:26:29Z

src/Platforms/AbstractMySQLPlatform.php

+
+        if ($srid !== null) {
+            // MySQL 8.0.3+ supports SRID attribute using conditional comment syntax
+            $sql .= sprintf(' /*!80003 SRID %d */', $srid);


Do we really need to emit those version-conditional comments? We should know which version of MySQL we're connecting to.

derrabus · 2025-12-10T09:28:35Z

src/Schema/MySQLSchemaManager.php

+        // MariaDB does not support SRS_ID column in information_schema.COLUMNS
+        // For MariaDB, SRID is parsed from COLUMN_TYPE conditional comments
+        $sridColumn = $this->platform instanceof MariaDBPlatform
+            ? 'NULL AS srs_id'
+            : 'c.SRS_ID AS srs_id';


Please don't perform instanceof checks on the platform. Move this logic into the platform classes instead.

derrabus · 2025-12-10T09:32:28Z

src/Types/GeoJSON.php

+        try {
+            return json_encode($this->data, JSON_THROW_ON_ERROR);
+        } catch (JsonException $e) {
+            throw new InvalidArgumentException(


How can a method without arguments raise errors on an "invalid argument"?

derrabus · 2025-12-10T09:34:14Z

src/Connection.php

+    /**
+     * Normalizes types array from positional or associative to associative format.
+     *
+     * @param array<int<0,max>, string|ParameterType|Type>|array<string, string|ParameterType|Type> $types
+     * @param list<string>                                                                           $columnNames
+     *
+     * @return array<string, string|ParameterType|Type>
+     */
+    private function normalizeTypes(array $types, array $columnNames): array
+    {


Why do we have to do this?

derrabus · 2025-12-10T09:35:06Z

tests/Functional/Schema/MySQL/SpatialTypesTest.php

+                    ->setUnquotedName('geom')
+                    ->setTypeName(Types::GEOMETRY)
+                    ->setGeometryType('POINT')
+                    ->setSrid(4326)


Is this magic number documented anywhere?

derrabus · 2025-12-10T09:36:06Z

tests/Functional/Schema/MySQL/SpatialTypesTest.php

+        // MariaDB does not support SRID specification in column definitions
+        if (! $this->connection->getDatabasePlatform() instanceof MariaDBPlatform) {
+            self::assertSame(4326, $sridGeom->getSrid());
+        }


So what is the expected behavior for MariaDB then?

derrabus · 2025-12-10T09:39:06Z

tests/Functional/Schema/PostgreSQL/PostGISTest.php

+        $alterSql   = $this->connection->getDatabasePlatform()->getAlterTableSQL($tableDiff);
+
+        // Execute ALTER TABLE
+        foreach ($alterSql as $sql) {
+            $this->connection->executeStatement($sql);
+        }


The schema manager can apply the diff for us. We don't have to feed the SQL statements into the connection ourselves.

derrabus · 2025-12-10T09:43:19Z

tests/TestUtil.php

+                }
+
+                $testConn->close();
+            }


Isn't this something our CI setup should do instead?

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

src/Types/GeometryType.php Show resolved Hide resolved

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 5 times, most recently 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

derrabus changed the base branch from 4.4.x to 4.5.x November 29, 2025 11:31

ddegasperi force-pushed the add-spatial-types branch from a3544b1 to 98c3be5 Compare December 1, 2025 08:04

ddegasperi added 6 commits December 5, 2025 15:24

ddegasperi force-pushed the add-spatial-types branch from 98c3be5 to e9e86f4 Compare December 5, 2025 14:27

derrabus requested changes Dec 10, 2025

View reviewed changes

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!

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!

jungleman12 commented Nov 16, 2025

Uh oh!

ddegasperi commented Dec 5, 2025

Uh oh!

derrabus left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ddegasperi commented Aug 18, 2025 •

edited

Loading

tibobaldwin commented Sep 6, 2025 •

edited

Loading