fix: add getSchemaIndexes and validate orphan indexes in createIndex

Adds getSchemaIndexes() to match the existing getSchemaAttributes()
pattern. When an index exists in physical schema but not metadata
(orphan), createIndex now validates the physical definition matches.
Mismatched orphans are dropped and recreated.

- Adapter: abstract getSchemaIndexes() + getSupportForSchemaIndexes()
- MariaDB: queries INFORMATION_SCHEMA.STATISTICS
- All others: default stubs (empty array / false)
- Database::createIndex: validates orphan index shape before reuse

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: abnegate

src/Database/Adapter.php

@@ -958,6 +958,13 @@ abstract public function getSupportForAttributes(): bool;
      */
     abstract public function getSupportForSchemaAttributes(): bool;
 
+    /**
+     * Are schema indexes supported?
+     *
+     * @return bool
+     */
+    abstract public function getSupportForSchemaIndexes(): bool;
+
     /**
      * Is index supported?
      *
@@ -1365,6 +1372,17 @@ abstract public function getInternalIndexesKeys(): array;
      */
     abstract public function getSchemaAttributes(string $collection): array;
 
+    /**
+     * Get Schema Indexes
+     *
+     * Returns physical index definitions from the database schema.
+     *
+     * @param string $collection
+     * @return array<Document>
+     * @throws DatabaseException
+     */
+    abstract public function getSchemaIndexes(string $collection): array;
+
     /**
      * Get the expected column type for a given attribute type.
      *

src/Database/Adapter/MariaDB.php

@@ -1845,6 +1845,58 @@ public function getSupportForSchemaAttributes(): bool
         return true;
     }
 
+    public function getSupportForSchemaIndexes(): bool
+    {
+        return true;
+    }
+
+    public function getSchemaIndexes(string $collection): array
+    {
+        $schema = $this->getDatabase();
+        $collection = $this->getNamespace() . '_' . $this->filter($collection);
+
+        try {
+            $stmt = $this->getPDO()->prepare('
+                SELECT
+                    INDEX_NAME as indexName,
+                    COLUMN_NAME as columnName,
+                    NON_UNIQUE as nonUnique,
+                    SEQ_IN_INDEX as seqInIndex,
+                    INDEX_TYPE as indexType,
+                    SUB_PART as subPart
+                FROM INFORMATION_SCHEMA.STATISTICS
+                WHERE TABLE_SCHEMA = :schema AND TABLE_NAME = :table
+                ORDER BY INDEX_NAME, SEQ_IN_INDEX
+            ');
+            $stmt->bindParam(':schema', $schema);
+            $stmt->bindParam(':table', $collection);
+            $stmt->execute();
+            $rows = $stmt->fetchAll();
+            $stmt->closeCursor();
+
+            $grouped = [];
+            foreach ($rows as $row) {
+                $name = $row['indexName'];
+                if (!isset($grouped[$name])) {
+                    $grouped[$name] = [
+                        '$id' => $name,
+                        'indexName' => $name,
+                        'indexType' => $row['indexType'],
+                        'nonUnique' => (int)$row['nonUnique'],
+                        'columns' => [],
+                        'lengths' => [],
+                    ];
+                }
+                $grouped[$name]['columns'][] = $row['columnName'];
+                $grouped[$name]['lengths'][] = $row['subPart'] !== null ? (int)$row['subPart'] : null;
+            }
+
+            return \array_map(fn ($idx) => new Document($idx), \array_values($grouped));
+        } catch (PDOException $e) {
+            throw new DatabaseException('Failed to get schema indexes', $e->getCode(), $e);
+        }
+    }
+
     /**
      * Set max execution time
      * @param int $milliseconds

src/Database/Adapter/Mongo.php

@@ -3601,6 +3601,16 @@ public function getSchemaAttributes(string $collection): array
         return [];
     }
 
+    public function getSupportForSchemaIndexes(): bool
+    {
+        return false;
+    }
+
+    public function getSchemaIndexes(string $collection): array
+    {
+        return [];
+    }
+
     /**
      * @param string $collection
      * @param array<int|string> $tenants

src/Database/Adapter/Pool.php

@@ -563,6 +563,16 @@ public function getSchemaAttributes(string $collection): array
         return $this->delegate(__FUNCTION__, \func_get_args());
     }
 
+    public function getSupportForSchemaIndexes(): bool
+    {
+        return $this->delegate(__FUNCTION__, \func_get_args());
+    }
+
+    public function getSchemaIndexes(string $collection): array
+    {
+        return $this->delegate(__FUNCTION__, \func_get_args());
+    }
+
     public function getTenantQuery(string $collection, string $alias = ''): string
     {
         return $this->delegate(__FUNCTION__, \func_get_args());

src/Database/Adapter/Postgres.php

@@ -2146,6 +2146,11 @@ public function getSupportForSchemaAttributes(): bool
         return false;
     }
 
+    public function getSupportForSchemaIndexes(): bool
+    {
+        return false;
+    }
+
     public function getSupportForUpserts(): bool
     {
         return true;

src/Database/Adapter/SQL.php

@@ -2328,6 +2328,16 @@ public function getSchemaAttributes(string $collection): array
         return [];
     }
 
+    public function getSchemaIndexes(string $collection): array
+    {
+        return [];
+    }
+
+    public function getSupportForSchemaIndexes(): bool
+    {
+        return false;
+    }
+
     public function getTenantQuery(
         string $collection,
         string $alias = '',

src/Database/Adapter/SQLite.php

@@ -974,6 +974,11 @@ public function getSupportForSchemaAttributes(): bool
         return false;
     }
 
+    public function getSupportForSchemaIndexes(): bool
+    {
+        return false;
+    }
+
     /**
      * Is upsert supported?
      *

src/Database/Database.php

@@ -4574,18 +4574,48 @@ public function createIndex(string $collection, string $id, string $type, array
         }
 
         $created = false;
+        $existsInSchema = false;
 
-        try {
-            $created = $this->adapter->createIndex($collection->getId(), $id, $type, $attributes, $lengths, $orders, $indexAttributesWithTypes, [], $ttl);
+        if ($this->adapter->getSupportForSchemaIndexes()) {
+            $schemaIndexes = $this->getSchemaIndexes($collection->getId());
+            $filteredId = $this->adapter->filter($id);
 
-            if (!$created) {
-                throw new DatabaseException('Failed to create index');
+            foreach ($schemaIndexes as $schemaIndex) {
+                if (\strtolower($schemaIndex->getId()) === \strtolower($filteredId)) {
+                    $schemaColumns = $schemaIndex->getAttribute('columns', []);
+                    $schemaLengths = $schemaIndex->getAttribute('lengths', []);
+
+                    $filteredAttributes = \array_map(fn ($a) => $this->adapter->filter($a), $attributes);
+                    $match = ($schemaColumns === $filteredAttributes && $schemaLengths === $lengths);
+
+                    if ($match) {
+                        $existsInSchema = true;
+                    } else {
+                        // Orphan index with wrong definition — drop so it
+                        // gets recreated with the correct shape.
+                        try {
+                            $this->adapter->deleteIndex($collection->getId(), $id);
+                        } catch (NotFoundException) {
+                        }
+                    }
+                    break;
+                }
+            }
+        }
+
+        if (!$existsInSchema) {
+            try {
+                $created = $this->adapter->createIndex($collection->getId(), $id, $type, $attributes, $lengths, $orders, $indexAttributesWithTypes, [], $ttl);
+
+                if (!$created) {
+                    throw new DatabaseException('Failed to create index');
+                }
+            } catch (DuplicateException) {
+                // Metadata check (lines above) already verified index is absent
+                // from metadata. A DuplicateException from the adapter means the
+                // index exists only in physical schema — an orphan from a prior
+                // partial failure. Skip creation and proceed to metadata update.
             }
-        } catch (DuplicateException $e) {
-            // Metadata check (lines above) already verified index is absent
-            // from metadata. A DuplicateException from the adapter means the
-            // index exists only in physical schema — an orphan from a prior
-            // partial failure. Skip creation and proceed to metadata update.
         }
 
         $collection->setAttribute('indexes', $index, Document::SET_TYPE_APPEND);
@@ -9220,6 +9250,11 @@ public function getSchemaAttributes(string $collection): array
         return $this->adapter->getSchemaAttributes($collection);
     }
 
+    public function getSchemaIndexes(string $collection): array
+    {
+        return $this->adapter->getSchemaIndexes($collection);
+    }
+
     /**
      * @param string $collectionId
      * @param string|null $documentId