feat: add UniqueConstraintViolationException and getLastException() (#9979)

Author: michalsn

rector.php

@@ -129,6 +129,7 @@
         ClassPropertyAssignToConstructorPromotionRector::class => [
             __DIR__ . '/system/Database/BaseResult.php',
             __DIR__ . '/system/Database/RawSql.php',
+            __DIR__ . '/system/Database/Exceptions/DatabaseException.php',
             __DIR__ . '/system/Debug/BaseExceptionHandler.php',
             __DIR__ . '/system/Debug/Exceptions.php',
             __DIR__ . '/system/Filters/Filters.php',

system/Database/BaseConnection.php

@@ -219,6 +219,14 @@ abstract class BaseConnection implements ConnectionInterface
      */
     protected $lastQuery;
 
+    /**
+     * The exception that would have been thrown on the last failed query
+     * if DBDebug were enabled. Null when the last query succeeded or when
+     * DBDebug is true (in which case the exception is thrown directly and
+     * this property is never set).
+     */
+    protected ?DatabaseException $lastException = null;
+
     /**
      * Connection ID
      *
@@ -698,8 +706,9 @@ public function query(string $sql, $binds = null, bool $setEscapeFlags = true, s
 
         // Run the query for real
         try {
-            $exception      = null;
-            $this->resultID = $this->simpleQuery($query->getQuery());
+            $exception           = null;
+            $this->lastException = null;
+            $this->resultID      = $this->simpleQuery($query->getQuery());
         } catch (DatabaseException $exception) {
             $this->resultID = false;
         }
@@ -737,11 +746,7 @@ public function query(string $sql, $binds = null, bool $setEscapeFlags = true, s
                 Events::trigger('DBQuery', $query);
 
                 if ($exception instanceof DatabaseException) {
-                    throw new DatabaseException(
-                        $exception->getMessage(),
-                        $exception->getCode(),
-                        $exception,
-                    );
+                    throw $exception;
                 }
 
                 return false;
@@ -1847,6 +1852,17 @@ public function isWriteType($sql): bool
      */
     abstract public function error(): array;
 
+    /**
+     * Returns the exception that would have been thrown on the last failed
+     * query if DBDebug were enabled. Returns null if the last query succeeded
+     * or if DBDebug is true (in which case the exception is always thrown
+     * directly and this method will always return null).
+     */
+    public function getLastException(): ?DatabaseException
+    {
+        return $this->lastException;
+    }
+
     /**
      * Insert ID
      *

system/Database/Exceptions/DatabaseException.php

@@ -15,9 +15,34 @@
 
 use CodeIgniter\Exceptions\HasExitCodeInterface;
 use CodeIgniter\Exceptions\RuntimeException;
+use Throwable;
 
 class DatabaseException extends RuntimeException implements ExceptionInterface, HasExitCodeInterface
 {
+    /**
+     * Native code returned by the database driver.
+     */
+    protected int|string $databaseCode = 0;
+
+    /**
+     * @param int|string $code Native database code (e.g. 1062, 23505, 23000/2601)
+     */
+    public function __construct(string $message = '', int|string $code = 0, ?Throwable $previous = null)
+    {
+        $this->databaseCode = $code;
+
+        // Keep Throwable::getCode() behavior BC-friendly for non-int DB codes.
+        parent::__construct($message, is_int($code) ? $code : 0, $previous);
+    }
+
+    /**
+     * Returns the native code from the database driver.
+     */
+    public function getDatabaseCode(): int|string
+    {
+        return $this->databaseCode;
+    }
+
     public function getExitCode(): int
     {
         return EXIT_DATABASE;

system/Database/Exceptions/UniqueConstraintViolationException.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Database\Exceptions;
+
+class UniqueConstraintViolationException extends DatabaseException
+{
+}

system/Database/MySQLi/Connection.php

@@ -15,6 +15,7 @@
 
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
+use CodeIgniter\Database\Exceptions\UniqueConstraintViolationException;
 use CodeIgniter\Database\TableName;
 use CodeIgniter\Exceptions\LogicException;
 use mysqli;
@@ -317,9 +318,16 @@ protected function execute(string $sql)
                 'trace'   => render_backtrace($e->getTrace()),
             ]);
 
+            // MySQL error 1062: ER_DUP_ENTRY – duplicate key value
+            $exception = $e->getCode() === 1062
+                ? new UniqueConstraintViolationException($e->getMessage(), $e->getCode(), $e)
+                : new DatabaseException($e->getMessage(), $e->getCode(), $e);
+
             if ($this->DBDebug) {
-                throw new DatabaseException($e->getMessage(), $e->getCode(), $e);
+                throw $exception;
             }
+
+            $this->lastException = $exception;
         }
 
         return false;

system/Database/OCI8/Connection.php

@@ -15,6 +15,7 @@
 
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
+use CodeIgniter\Database\Exceptions\UniqueConstraintViolationException;
 use CodeIgniter\Database\Query;
 use CodeIgniter\Database\TableName;
 use ErrorException;
@@ -236,10 +237,27 @@ protected function execute(string $sql)
 
             oci_set_prefetch($this->stmtId, 1000);
 
-            $result          = oci_execute($this->stmtId, $this->commitMode) ? $this->stmtId : false;
+            $result = oci_execute($this->stmtId, $this->commitMode) ? $this->stmtId : false;
+
+            if ($result === false) {
+                // ORA-00001: unique constraint violated
+                $error     = $this->error();
+                $exception = $error['code'] === 1
+                    ? new UniqueConstraintViolationException((string) $error['message'], $error['code'])
+                    : new DatabaseException((string) $error['message'], $error['code']);
+
+                if ($this->DBDebug) {
+                    throw $exception;
+                }
+
+                $this->lastException = $exception;
+
+                return false;
+            }
+
             $insertTableName = $this->parseInsertTableName($sql);
 
-            if ($result && $insertTableName !== '') {
+            if ($insertTableName !== '') {
                 $this->lastInsertedTableName = $insertTableName;
             }
 
@@ -254,9 +272,17 @@ protected function execute(string $sql)
                 'trace'   => render_backtrace($trace),
             ]);
 
+            // ORA-00001: unique constraint violated
+            $error     = $this->error();
+            $exception = $error['code'] === 1
+                ? new UniqueConstraintViolationException((string) $error['message'], $error['code'], $e)
+                : new DatabaseException((string) $error['message'], $error['code'], $e);
+
             if ($this->DBDebug) {
-                throw new DatabaseException($e->getMessage(), $e->getCode(), $e);
+                throw $exception;
             }
+
+            $this->lastException = $exception;
         }
 
         return false;
@@ -615,25 +641,25 @@ protected function bindParams($params)
      */
     public function error(): array
     {
-        // oci_error() returns an array that already contains
-        // 'code' and 'message' keys, but it can return false
-        // if there was no error ....
-        $error     = oci_error();
+        // oci_error() is resource-specific: check each resource in priority order
+        // and return the first one that actually has an error. This ensures that
+        // e.g. oci_parse() failures (error on connID) are found even when stmtId
+        // holds a stale valid resource from the previous successful query.
         $resources = [$this->cursorId, $this->stmtId, $this->connID];
 
         foreach ($resources as $resource) {
             if (is_resource($resource)) {
                 $error = oci_error($resource);
-                break;
+
+                if (is_array($error)) {
+                    return $error;
+                }
             }
         }
 
-        return is_array($error)
-            ? $error
-            : [
-                'code'    => '',
-                'message' => '',
-            ];
+        $error = oci_error();
+
+        return is_array($error) ? $error : ['code' => '', 'message' => ''];
     }
 
     public function insertID(): int