add docs

Author: michalsn

user_guide_src/source/changelogs/v4.8.0.rst

@@ -123,6 +123,9 @@ Others
 ------
 
 - Added new ``timezone`` option to connection array in ``Config\Database`` config. This ensures consistent timestamps between model operations and database functions like ``NOW()``. Supported drivers: **MySQLi**, **Postgre**, and **OCI8**. See :ref:`database-config-timezone` for details.
+- Added :php:class:`UniqueConstraintViolationException <CodeIgniter\\Database\\Exceptions\\UniqueConstraintViolationException>` which extends ``DatabaseException`` and is thrown on duplicate key (unique constraint) violations across all database drivers. See :ref:`database-unique-constraint-violation`.
+- Added ``$db->getLastException()`` which returns the typed exception even when ``DBDebug`` is ``false``. See :ref:`database-get-last-exception`.
+- Added ``DatabaseException::getDatabaseCode()`` returning the native driver error code as ``int|string``; ``getCode()`` is constrained to ``int`` by PHP's ``Throwable`` interface and cannot carry string SQLSTATE codes.
 
 Model
 =====

user_guide_src/source/database/queries.rst

@@ -203,15 +203,63 @@ placeholders in the query:
 Handling Errors
 ***************
 
+.. note:: It is strongly recommended to keep ``DBDebug`` set to ``true``
+    (the default). This ensures all query failures surface immediately as
+    exceptions, preventing silent data corruption. Setting it to ``false``
+    is considered legacy behaviour and may be deprecated in a future version.
+
+DBDebug Enabled (Recommended)
+=============================
+
+When :ref:`DBDebug <database-config-explanation-of-values>` is ``true``
+(the default), any query failure throws a ``DatabaseException`` or one of
+its subclasses, which you can catch and handle:
+
+.. literalinclude:: queries/030.php
+
+.. _database-unique-constraint-violation:
+
+UniqueConstraintViolationException
+----------------------------------
+
+.. versionadded:: 4.8.0
+
+``UniqueConstraintViolationException`` extends ``DatabaseException`` and is
+thrown specifically when a query fails due to a duplicate key or unique
+constraint violation. Catching it separately allows you to handle this case
+without inspecting raw driver-specific error codes.
+
+DBDebug Disabled
+================
+
+When ``DBDebug`` is ``false``, query failures return ``false`` instead of
+throwing. Two methods are available to inspect what went wrong.
+
 $db->error()
-============
+------------
 
-If you need to get the last error that has occurred, the ``error()`` method
-will return an array containing its code and message. Here's a quick
-example:
+The ``error()`` method returns an array with ``code`` and ``message`` keys
+describing the last error. Error codes are driver-specific (an **int** for
+MySQLi, SQLite3, and OCI8; a SQLSTATE **string** for Postgre and SQLSRV):
 
 .. literalinclude:: queries/015.php
 
+.. _database-get-last-exception:
+
+$db->getLastException()
+-----------------------
+
+.. versionadded:: 4.8.0
+
+``getLastException()`` returns the typed exception that would have been
+thrown had ``DBDebug`` been ``true``. This is the recommended way to
+distinguish between failure types (e.g., a unique constraint violation vs.
+another database error) without enabling ``DBDebug``:
+
+.. literalinclude:: queries/031.php
+
+.. note:: ``getLastException()`` is reset to ``null`` at the start of every
+    query. Inspect it immediately after the failed operation.
 
 ****************
 Prepared Queries

user_guide_src/source/database/queries/030.php

@@ -0,0 +1,12 @@
+<?php
+
+use CodeIgniter\Database\Exceptions\DatabaseException;
+use CodeIgniter\Database\Exceptions\UniqueConstraintViolationException;
+
+try {
+    $db->table('users')->insert(['email' => 'duplicate@example.com']);
+} catch (UniqueConstraintViolationException $e) {
+    // Duplicate key — handle gracefully
+} catch (DatabaseException $e) {
+    // Other database error
+}

user_guide_src/source/database/queries/031.php

@@ -0,0 +1,9 @@
+<?php
+
+use CodeIgniter\Database\Exceptions\UniqueConstraintViolationException;
+
+$inserted = $db->table('users')->insert(['email' => 'duplicate@example.com']);
+
+if (! $inserted && $db->getLastException() instanceof UniqueConstraintViolationException) {
+    // Handle duplicate key violation
+}

user_guide_src/source/general/errors.rst

@@ -204,6 +204,18 @@ or when it is temporarily lost:
 
 This provides an exit code of 8.
 
+UniqueConstraintViolationException
+----------------------------------
+
+.. versionadded:: 4.8.0
+
+``UniqueConstraintViolationException`` extends ``DatabaseException`` and is thrown when a query
+fails due to a duplicate key or unique constraint violation. It is supported by all database drivers.
+
+.. literalinclude:: errors/019.php
+
+See :ref:`database-unique-constraint-violation` for full usage details.
+
 RedirectException
 -----------------
 

user_guide_src/source/general/errors/019.php

@@ -0,0 +1,9 @@
+<?php
+
+use CodeIgniter\Database\Exceptions\UniqueConstraintViolationException;
+
+try {
+    $db->table('users')->insert(['email' => 'duplicate@example.com']);
+} catch (UniqueConstraintViolationException $e) {
+    // Handle duplicate key violation
+}