added backwards compatibility

Signed-off-by: Andy Miller <rhuk@mac.com>

Author: rhukster

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [2.3.1] - 2026-03-09
+
+### Improvements
+- **SQLite backward compatibility**: The `RETURNING` clause (requires SQLite 3.35.0+) is now optional. On older SQLite versions (3.24.0+), a fallback `SELECT` query is used to retrieve `doc_id` after upsert operations. This lowers the minimum SQLite requirement from 3.35.0 to 3.24.0 while preserving optimal performance on newer versions.
+
 ## [2.3.0] - 2026-02-13
 
 ### Security Fixes

README.md

@@ -81,11 +81,11 @@ A powerful, pure-PHP search engine library with advanced full-text search capabi
 
 Important: SQLite FTS5 required
 - YetiSearch uses SQLite FTS5 virtual tables for full‑text search and BM25 ranking. Your PHP build must link against a SQLite library compiled with FTS5 (ENABLE_FTS5).
-- **SQLite 3.35.0 or higher** is required (for `RETURNING` clause support used in document indexing).
+- **SQLite 3.24.0 or higher** is required (for `ON CONFLICT` upsert support). SQLite 3.35.0+ is recommended for best performance (uses `RETURNING` clause to avoid extra queries).
 - Quick check: `php scripts/check_sqlite_features.php` should report "FTS5: OK" and show the SQLite version. On macOS, Homebrew PHP typically includes a recent SQLite with FTS5; some system PHP builds may not.
 
 - PHP 7.4 or higher
-- SQLite 3.35.0 or higher
+- SQLite 3.24.0 or higher (3.35.0+ recommended)
 - SQLite3 PHP extension
 - PDO PHP extension with SQLite driver
 - Mbstring PHP extension

src/Storage/SqliteStorage.php

@@ -19,6 +19,7 @@ class SqliteStorage implements StorageInterface
     private ?bool $rtreeSupport = null;
     private bool $useTermsIndex = false;
     private ?bool $hasMathFunctions = null;
+    private bool $hasReturningSupport = false;
     private array $ftsColumnsCache = [];
     private array $spatialEnabledCache = [];
     private bool $externalContentDefault = false;
@@ -125,6 +126,10 @@ public function connect(array $config): void
             // Improve query planning on connect
             $this->connection->exec('PRAGMA optimize');
 
+            // Detect SQLite version for RETURNING clause support (3.35.0+)
+            $sqliteVersion = $this->connection->query('SELECT sqlite_version()')->fetchColumn();
+            $this->hasReturningSupport = version_compare($sqliteVersion, '3.35.0', '>=');
+
             // Detect availability of math functions for Haversine
             try {
                 $this->connection->query('SELECT sin(0.0), cos(0.0), pi()')->fetch();
@@ -398,8 +403,7 @@ public function insert(string $index, array $document): void
             $schema = $this->getSchemaMode($index);
             $docId = null;
             if ($schema === 'external') {
-                // Use RETURNING to get doc_id directly without extra SELECT query (SQLite 3.35+)
-                $sql = "
+                $upsertSql = "
                     INSERT INTO {$index} (id, content, metadata, language, type, timestamp)
                     VALUES (?, ?, ?, ?, ?, ?)
                     ON CONFLICT(id) DO UPDATE SET
@@ -408,12 +412,21 @@ public function insert(string $index, array $document): void
                         language=excluded.language,
                         type=excluded.type,
                         timestamp=excluded.timestamp
-                    RETURNING doc_id
                 ";
-                $stmt = $this->connection->prepare($sql);
-                $stmt->execute([$id, $content, $metadata, $language, $type, $timestamp]);
-                $docId = $stmt->fetchColumn();
-                $stmt->closeCursor(); // Must close cursor before next operation
+                if ($this->hasReturningSupport) {
+                    // Use RETURNING to get doc_id directly without extra SELECT query (SQLite 3.35+)
+                    $stmt = $this->connection->prepare($upsertSql . " RETURNING doc_id");
+                    $stmt->execute([$id, $content, $metadata, $language, $type, $timestamp]);
+                    $docId = $stmt->fetchColumn();
+                    $stmt->closeCursor();
+                } else {
+                    // Fallback for older SQLite: upsert then SELECT doc_id
+                    $stmt = $this->connection->prepare($upsertSql);
+                    $stmt->execute([$id, $content, $metadata, $language, $type, $timestamp]);
+                    $docId = $this->connection->prepare("SELECT doc_id FROM {$index} WHERE id = ?");
+                    $docId->execute([$id]);
+                    $docId = $docId->fetchColumn();
+                }
             } else {
                 $sql = "
                     INSERT OR REPLACE INTO {$index}
@@ -493,8 +506,7 @@ public function insertBatch(string $index, array $documents): void
             if ($schema === 'external') {
                 // Use ON CONFLICT DO UPDATE to preserve doc_id on updates.
                 // INSERT OR REPLACE would delete and re-insert, generating new doc_id.
-                // Use RETURNING to get the doc_id for FTS/spatial indexing.
-                $docStmt = $this->connection->prepare("
+                $upsertSql = "
                     INSERT INTO {$index} (id, content, metadata, language, type, timestamp)
                     VALUES (?, ?, ?, ?, ?, ?)
                     ON CONFLICT(id) DO UPDATE SET
@@ -503,8 +515,15 @@ public function insertBatch(string $index, array $documents): void
                         language=excluded.language,
                         type=excluded.type,
                         timestamp=excluded.timestamp
-                    RETURNING doc_id
-                ");
+                ";
+                if ($this->hasReturningSupport) {
+                    $upsertSql .= " RETURNING doc_id";
+                }
+                $docStmt = $this->connection->prepare($upsertSql);
+                // Prepare fallback SELECT for older SQLite without RETURNING support
+                $docIdFallbackStmt = !$this->hasReturningSupport
+                    ? $this->connection->prepare("SELECT doc_id FROM {$index} WHERE id = ?")
+                    : null;
             } else {
                 $docStmt = $this->connection->prepare("
                     INSERT OR REPLACE INTO {$index}
@@ -596,9 +615,14 @@ public function insertBatch(string $index, array $documents): void
 
                 // Collect FTS data for batch insert
                 if ($schema === 'external') {
-                    // Get doc_id from RETURNING clause (works for both inserts and updates)
-                    $docId = $docStmt->fetchColumn();
-                    $docStmt->closeCursor();
+                    // Get doc_id - use RETURNING if available, otherwise fallback SELECT
+                    if ($this->hasReturningSupport) {
+                        $docId = $docStmt->fetchColumn();
+                        $docStmt->closeCursor();
+                    } else {
+                        $docIdFallbackStmt->execute([$id]);
+                        $docId = $docIdFallbackStmt->fetchColumn();
+                    }
                     $ftsData[] = [$docId, $this->getFieldText($document['content'], 'content', $index)];
                 } else {
                     $values = [$id];