fix: sqlite 21 bad parameter or other API misuse triggered sometimes due to different scaler type

Author: arabcoders

src/Libs/Database/PDO/PDOAdapter.php

@@ -207,13 +207,12 @@ public function insert(iState $entity): iState
             }
 
             $this->db->query($this->stmt['insert'], $data, options: [
-                'on_failure' => function (Throwable $e) use ($entity) {
-                    if (false === str_contains($e->getMessage(), '21 bad parameter or other API misuse')) {
-                        throw $e;
-                    }
-                    $this->stmt['insert'] = null;
-                    return $this->insert($entity);
-                },
+                'on_failure' => fn(Throwable $e) => $this->retryPreparedWrite(
+                    key: 'insert',
+                    sql: $this->pdoInsert('state', iState::ENTITY_KEYS),
+                    data: $data,
+                    e: $e,
+                ),
             ]);
 
             $entity->id = (int) $this->db->lastInsertId();
@@ -432,13 +431,12 @@ public function update(iState $entity): iState
             }
 
             $this->db->query($this->stmt['update'], $data, options: [
-                'on_failure' => function (Throwable $e) use ($entity) {
-                    if (false === str_contains($e->getMessage(), '21 bad parameter or other API misuse')) {
-                        throw $e;
-                    }
-                    $this->stmt['update'] = null;
-                    return $this->update($entity);
-                },
+                'on_failure' => fn(Throwable $e) => $this->retryPreparedWrite(
+                    key: 'update',
+                    sql: $this->pdoUpdate('state', iState::ENTITY_KEYS),
+                    data: $data,
+                    e: $e,
+                ),
             ]);
         } catch (PDOException $e) {
             $this->stmt['update'] = null;
@@ -810,6 +808,26 @@ private function pdoUpdate(string $table, array $columns): string
         return trim(str_replace('{place} = {holder}', implode(', ', $placeholders), $queryString));
     }
 
+    /**
+     * Retry a cached write statement once when sqlite reports prepared statement misuse.
+     *
+     * @param string $key Cached statement key.
+     * @param string $sql SQL statement to prepare.
+     * @param array $data Bound statement values.
+     * @param Throwable $e Triggering exception.
+     */
+    private function retryPreparedWrite(string $key, string $sql, array $data, Throwable $e): PDOStatement
+    {
+        if (false === str_contains($e->getMessage(), '21 bad parameter or other API misuse')) {
+            throw $e;
+        }
+
+        $statement = $this->db->prepare($sql);
+        $this->stmt[$key] = $statement;
+
+        return $this->db->query($statement, $data);
+    }
+
     /**
      * Find db entity using external id.
      * External id format is: (db_name)://(id)

tests/Database/PDOAdapterTest.php

@@ -21,7 +21,10 @@
 use Monolog\Handler\TestHandler;
 use Monolog\Logger;
 use PDO;
+use PDOException;
+use PDOStatement;
 use Psr\SimpleCache\CacheInterface;
+use ReflectionMethod;
 use Symfony\Component\Console\Input\ArrayInput;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\NullOutput;
@@ -346,6 +349,65 @@ public function test_update_conditions(): void
         );
     }
 
+    public function test_retryPreparedWrite_returns_statement_for_bad_parameter_retry(): void
+    {
+        assert($this->db instanceof PDOAdapter);
+
+        $item = $this->db->insert(new StateEntity($this->testEpisode));
+        $item->title = 'Retried Title';
+
+        $data = $item->getAll();
+        $data[iState::COLUMN_UPDATED_AT] = time();
+
+        foreach (iState::ENTITY_ARRAY_KEYS as $key) {
+            if (!(null !== ($data[$key] ?? null) && true === is_array($data[$key]))) {
+                continue;
+            }
+
+            ksort($data[$key]);
+            $data[$key] = json_encode($data[$key], flags: JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+        }
+
+        $pdoUpdate = new ReflectionMethod($this->db, 'pdoUpdate');
+        $sql = $pdoUpdate->invoke($this->db, 'state', iState::ENTITY_KEYS);
+
+        $retryPreparedWrite = new ReflectionMethod($this->db, 'retryPreparedWrite');
+        $stmt = $retryPreparedWrite->invoke(
+            $this->db,
+            'update',
+            $sql,
+            $data,
+            new PDOException('21 bad parameter or other API misuse'),
+        );
+
+        $this->assertInstanceOf(PDOStatement::class, $stmt, 'Retry path should return a PDO statement, not an entity.');
+        $this->assertSame(
+            'Retried Title',
+            $this->db->get($item)->title,
+            'Retry path should execute the rebuilt update statement successfully.'
+        );
+    }
+
+    public function test_retryPreparedWrite_rethrows_unrelated_errors(): void
+    {
+        assert($this->db instanceof PDOAdapter);
+
+        $retryPreparedWrite = new ReflectionMethod($this->db, 'retryPreparedWrite');
+
+        $this->checkException(
+            closure: fn() => $retryPreparedWrite->invoke(
+                $this->db,
+                'update',
+                'UPDATE state SET title = :title WHERE id = :id',
+                ['title' => 'Ignored', 'id' => 1],
+                new PDOException('some other database problem'),
+            ),
+            reason: 'Retry helper should only intercept sqlite API misuse errors.',
+            exception: PDOException::class,
+            exceptionMessage: 'some other database problem',
+        );
+    }
+
     public function test_duplicates_uses_cache(): void
     {
         $cache = $this->makeCacheStub();