Add PostgreSQL index access method reflection support

This adds the ability to reflect PostgreSQL index access methods
(gin, gist, spgist, brin, hash) when describing indexes.

Changes:
- Add `accessMethod` property to Index class with constants for
  PostgreSQL access methods (GIN, GIST, SPGIST, BRIN, HASH)
- Update describeIndexQuery() to join pg_am and fetch amname
- Update describeIndexes() and convertIndexDescription() to include
  accessMethod in result for non-btree indexes
- Update indexSql() to generate USING clause for non-btree indexes

This enables migrations to properly reflect and regenerate indexes
that use specialized PostgreSQL access methods.

Refs cakephp/migrations#1053

Author: dereuromark

src/Database/Schema/Index.php

@@ -38,6 +38,17 @@ class Index
      */
     public const FULLTEXT = 'fulltext';
 
+    /**
+     * PostgreSQL index access methods
+     *
+     * @var string
+     */
+    public const GIN = 'gin';
+    public const GIST = 'gist';
+    public const SPGIST = 'spgist';
+    public const BRIN = 'brin';
+    public const HASH = 'hash';
+
     /**
      * Constructor
      *
@@ -48,6 +59,7 @@ class Index
      * @param array<string>|null $order The sort order of the index columns.
      * @param array<string>|null $include The included columns for covering indexes.
      * @param ?string $where The where clause for partial indexes.
+     * @param ?string $accessMethod The index access method for PostgreSQL (gin, gist, spgist, brin, hash).
      */
     public function __construct(
         protected string $name,
@@ -57,6 +69,7 @@ public function __construct(
         protected ?array $order = null,
         protected ?array $include = null,
         protected ?string $where = null,
+        protected ?string $accessMethod = null,
     ) {
     }
 
@@ -231,6 +244,32 @@ public function getWhere(): ?string
         return $this->where;
     }
 
+    /**
+     * Set the index access method for PostgreSQL.
+     *
+     * PostgreSQL supports multiple index access methods: btree (default),
+     * gin, gist, spgist, brin, and hash.
+     *
+     * @param ?string $accessMethod The access method (gin, gist, spgist, brin, hash).
+     * @return $this
+     */
+    public function setAccessMethod(?string $accessMethod)
+    {
+        $this->accessMethod = $accessMethod;
+
+        return $this;
+    }
+
+    /**
+     * Get the index access method for PostgreSQL.
+     *
+     * @return ?string
+     */
+    public function getAccessMethod(): ?string
+    {
+        return $this->accessMethod;
+    }
+
     /**
      * Utility method that maps an array of index options to this object's methods.
      *
@@ -241,7 +280,7 @@ public function getWhere(): ?string
     public function setAttributes(array $attributes)
     {
         // Valid Options
-        $validOptions = ['columns', 'type', 'name', 'length', 'order', 'include', 'where'];
+        $validOptions = ['columns', 'type', 'name', 'length', 'order', 'include', 'where', 'accessMethod'];
         foreach ($attributes as $attr => $value) {
             if (!in_array($attr, $validOptions, true)) {
                 throw new RuntimeException(sprintf('"%s" is not a valid index option.', $attr));
@@ -268,6 +307,7 @@ public function toArray(): array
             'order' => $this->getOrder(),
             'include' => $this->getInclude(),
             'where' => $this->getWhere(),
+            'accessMethod' => $this->getAccessMethod(),
         ];
     }
 }

src/Database/Schema/PostgresSchemaDialect.php

@@ -375,12 +375,14 @@ private function describeIndexQuery(): string
         a.attname,
         i.indisprimary,
         i.indisunique,
-        i.indnkeyatts
+        i.indnkeyatts,
+        am.amname
         FROM pg_catalog.pg_namespace n
         INNER JOIN pg_catalog.pg_class c ON (n.oid = c.relnamespace)
         INNER JOIN pg_catalog.pg_index i ON (c.oid = i.indrelid)
         INNER JOIN pg_catalog.pg_class c2 ON (c2.oid = i.indexrelid)
         INNER JOIN pg_catalog.pg_attribute a ON (a.attrelid = c.oid AND i.indrelid::regclass = a.attrelid::regclass)
+        INNER JOIN pg_catalog.pg_am am ON (c2.relam = am.oid)
         WHERE n.nspname = ?
         AND a.attnum = ANY(i.indkey)
         AND c.relname = ?
@@ -423,6 +425,11 @@ public function convertIndexDescription(TableSchema $schema, array $row): void
                 'type' => $type,
                 'columns' => [],
             ];
+            // Include access method for non-btree indexes
+            $accessMethod = $row['amname'] ?? 'btree';
+            if ($accessMethod !== 'btree') {
+                $index['accessMethod'] = $accessMethod;
+            }
         }
         $index['columns'][] = $row['attname'];
         $schema->addIndex($name, $index);
@@ -458,6 +465,11 @@ public function describeIndexes(string $tableName): array
                     'columns' => [],
                     'length' => [],
                 ];
+                // Include access method for non-btree indexes
+                $accessMethod = $row['amname'] ?? 'btree';
+                if ($accessMethod !== 'btree') {
+                    $indexes[$name]['accessMethod'] = $accessMethod;
+                }
             }
             if ($constraint) {
                 $indexes[$name]['constraint'] = $constraint;
@@ -917,6 +929,14 @@ public function indexSql(TableSchema $schema, string $name): string
             $this->_driver->quoteIdentifier(...),
             (array)$index->getColumns(),
         );
+
+        // Build USING clause for non-btree access methods (gin, gist, spgist, brin, hash)
+        $using = '';
+        $accessMethod = $index->getAccessMethod();
+        if ($accessMethod !== null) {
+            $using = ' USING ' . $accessMethod;
+        }
+
         $include = '';
         if ($index->getInclude()) {
             $included = array_map(
@@ -927,9 +947,10 @@ public function indexSql(TableSchema $schema, string $name): string
         }
 
         return sprintf(
-            'CREATE INDEX %s ON %s (%s)%s',
+            'CREATE INDEX %s ON %s%s (%s)%s',
             $this->_driver->quoteIdentifier($name),
             $this->_driver->quoteIdentifier($schema->name()),
+            $using,
             implode(', ', $columns),
             $include,
         );