Add spatial index support for PostgreSQL/PostGIS

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)

Author: ddegasperi

src/Platforms/AbstractPlatform.php

@@ -1251,11 +1251,22 @@ public function getCreateIndexSQL(Index $index, string $table): string
         }
 
         $query  = 'CREATE ' . $this->getCreateIndexSQLFlags($index) . 'INDEX ' . $name . ' ON ' . $table;
+        $query .= $this->getIndexMethodSQL($index);
         $query .= ' (' . implode(', ', $index->getQuotedColumns($this)) . ')' . $this->getPartialIndexSQL($index);
 
         return $query;
     }
 
+    /**
+     * Returns the index method clause for platforms that support it.
+     *
+     * @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy.
+     */
+    protected function getIndexMethodSQL(Index $index): string
+    {
+        return '';
+    }
+
     /**
      * Adds condition for partial index.
      */

src/Platforms/PostgreSQL/PostgreSQLMetadataProvider.php

@@ -388,11 +388,13 @@ private function getIndexColumns(?string $schemaName, ?string $tableName): itera
                    ic.relname,
                    i.indisunique,
                    pg_get_expr(indpred, indrelid),
-                   attname
+                   attname,
+                   am.amname
             FROM pg_index i
                      JOIN pg_class AS c ON c.oid = i.indrelid
                      JOIN pg_namespace n ON n.oid = c.relnamespace
                      JOIN pg_class AS ic ON ic.oid = i.indexrelid
+                     JOIN pg_am am ON am.oid = ic.relam
                      JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS keys(attnum, ord)
                           ON TRUE
                      JOIN pg_attribute a
@@ -409,11 +411,21 @@ private function getIndexColumns(?string $schemaName, ?string $tableName): itera
         );
 
         foreach ($this->connection->iterateNumeric($sql, $params) as $row) {
+            // Determine index type based on access method and uniqueness
+            // GIST indexes are used for spatial data in PostGIS
+            if ($row[6] === 'gist') {
+                $type = IndexType::SPATIAL;
+            } elseif ($row[3]) {
+                $type = IndexType::UNIQUE;
+            } else {
+                $type = IndexType::REGULAR;
+            }
+
             yield new IndexColumnMetadataRow(
                 schemaName: $row[0],
                 tableName: $row[1],
                 indexName: $row[2],
-                type: $row[3] ? IndexType::UNIQUE : IndexType::REGULAR,
+                type: $type,
                 isClustered: false,
                 predicate: $row[4],
                 columnName: $row[5],

src/Platforms/PostgreSQLPlatform.php

@@ -889,6 +889,20 @@ public function createMetadataProvider(Connection $connection): PostgreSQLMetada
         return new PostgreSQLMetadataProvider($connection, $this);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * For spatial indexes on PostgreSQL/PostGIS, we need to use GIST index method.
+     */
+    protected function getIndexMethodSQL(Index $index): string
+    {
+        if ($index->getType() === Index\IndexType::SPATIAL) {
+            return ' USING GIST';
+        }
+
+        return '';
+    }
+
     public function createSchemaManager(Connection $connection): PostgreSQLSchemaManager
     {
         return new PostgreSQLSchemaManager($connection, $this);

src/Schema/PostgreSQLSchemaManager.php

@@ -168,12 +168,20 @@ protected function _getPortableTableIndexesList(array $rows, string $tableName):
         return parent::_getPortableTableIndexesList(array_map(
             /** @param array<string, mixed> $row */
             static function (array $row): array {
+                $flags = [];
+
+                // GIST indexes are used for spatial data in PostGIS
+                if (isset($row['index_method']) && $row['index_method'] === 'gist') {
+                    $flags = ['SPATIAL'];
+                }
+
                 return [
                     'key_name' => $row['relname'],
                     'non_unique' => ! $row['indisunique'],
                     'primary' => (bool) $row['indisprimary'],
                     'where' => $row['where'],
                     'column_name' => $row['attname'],
+                    'flags' => $flags,
                 ];
             },
             $rows,
@@ -458,11 +466,13 @@ protected function selectIndexColumns(string $databaseName, ?string $tableName =
                    i.indkey,
                    i.indrelid,
                    pg_get_expr(indpred, indrelid) AS "where",
-                   quote_ident(attname) AS attname
+                   quote_ident(attname) AS attname,
+                   am.amname AS index_method
               FROM pg_index i
                    JOIN pg_class AS c ON c.oid = i.indrelid
                    JOIN pg_namespace n ON n.oid = c.relnamespace
                    JOIN pg_class AS ic ON ic.oid = i.indexrelid
+                   JOIN pg_am am ON am.oid = ic.relam
                    JOIN LATERAL UNNEST(i.indkey) WITH ORDINALITY AS keys(attnum, ord)
                         ON TRUE
                    JOIN pg_attribute a

tests/Functional/Schema/PostgreSQL/PostGISTest.php

@@ -6,6 +6,8 @@
 
 use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
 use Doctrine\DBAL\Schema\Column;
+use Doctrine\DBAL\Schema\Index;
+use Doctrine\DBAL\Schema\Index\IndexType;
 use Doctrine\DBAL\Schema\PrimaryKeyConstraint;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Tests\Functional\SpatialTestCase;
@@ -344,4 +346,55 @@ public function testAlterTableAlterSpatialColumn(): void
         self::assertSame('Polygon', $geog->getGeometryType());
         self::assertSame(4267, $geog->getSrid());
     }
+
+    public function testSpatialIndex(): void
+    {
+        $index = Index::editor()
+            ->setUnquotedName('spatial_idx')
+            ->setType(IndexType::SPATIAL)
+            ->setUnquotedColumnNames('location')
+            ->create();
+
+        $table = Table::editor()
+            ->setUnquotedName(self::TABLE_NAME)
+            ->setColumns(
+                Column::editor()
+                    ->setUnquotedName('id')
+                    ->setTypeName(Types::INTEGER)
+                    ->setAutoincrement(true)
+                    ->create(),
+                Column::editor()
+                    ->setUnquotedName('location')
+                    ->setTypeName(Types::GEOMETRY)
+                    ->setGeometryType('POINT')
+                    ->setSrid(4326)
+                    ->create(),
+            )
+            ->setPrimaryKeyConstraint(
+                PrimaryKeyConstraint::editor()
+                    ->setUnquotedColumnNames('id')
+                    ->create(),
+            )
+            ->setIndexes($index)
+            ->create();
+
+        $schemaManager = $this->connection->createSchemaManager();
+        $schemaManager->createTable($table);
+
+        $onlineTable = $schemaManager->introspectTableByUnquotedName(self::TABLE_NAME);
+
+        // Verify the table structure is maintained
+        self::assertTrue(
+            $schemaManager->createComparator()
+                ->compareTables($table, $onlineTable)
+                ->isEmpty(),
+        );
+
+        // Verify the spatial index exists
+        self::assertTrue($onlineTable->hasIndex('spatial_idx'));
+
+        // Verify the index type is SPATIAL
+        $spatialIndex = $onlineTable->getIndex('spatial_idx');
+        self::assertSame(IndexType::SPATIAL, $spatialIndex->getType());
+    }
 }

tests/Platforms/PostgreSQLPlatformTest.php

@@ -9,6 +9,7 @@
 use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\ColumnDiff;
 use Doctrine\DBAL\Schema\ForeignKeyConstraint;
+use Doctrine\DBAL\Schema\Index;
 use Doctrine\DBAL\Schema\Name\OptionallyQualifiedName;
 use Doctrine\DBAL\Schema\PrimaryKeyConstraint;
 use Doctrine\DBAL\Schema\Sequence;
@@ -1273,4 +1274,18 @@ public function testReturnsGeographyAsGeoJSONSQL(): void
             $this->platform->getGeographyAsGeoJSONSQL('geog_col'),
         );
     }
+
+    public function testCreateSpatialIndexSQL(): void
+    {
+        $index = Index::editor()
+            ->setUnquotedName('spatial_idx')
+            ->setType(Index\IndexType::SPATIAL)
+            ->setUnquotedColumnNames('location')
+            ->create();
+
+        self::assertSame(
+            'CREATE INDEX spatial_idx ON spatial_table USING GIST (location)',
+            $this->platform->getCreateIndexSQL($index, 'spatial_table'),
+        );
+    }
 }