fix deferred writes for DatabaseHandler

Author: michalsn

README.md

@@ -9,7 +9,7 @@ config classes for CodeIgniter 4 framework.
 [![Coverage Status](https://coveralls.io/repos/github/codeigniter4/settings/badge.svg?branch=develop)](https://coveralls.io/github/codeigniter4/settings?branch=develop)
 
 ![PHP](https://img.shields.io/badge/PHP-%5E8.1-blue)
-![CodeIgniter](https://img.shields.io/badge/CodeIgniter-%5E4.3-blue)
+![CodeIgniter](https://img.shields.io/badge/CodeIgniter-%5E4.2.3-blue)
 ![License](https://img.shields.io/badge/License-MIT-blue)
 
 ## Installation

composer.json

@@ -21,7 +21,7 @@
     },
     "require-dev": {
         "codeigniter4/devkit": "^1.3",
-        "codeigniter4/framework": "^4.3.0"
+        "codeigniter4/framework": "^4.2.3"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,

docs/configuration.md

@@ -29,7 +29,8 @@ public $handlers = ['database'];
 ### Deferred writes
 
 Handlers like `database` and `file` support deferred writes. When `deferWrites` is enabled, multiple `set()` and `forget()` calls
-are batched into the minimum number of database calls or file writes. The actual changes happen during the `post_system` event.
+are batched and persisted efficiently at the end of the request during the `post_system` event. This minimizes the number of
+database queries or file I/O operations, improving performance for write-heavy operations.
 
 ### Multiple handlers
 
@@ -80,17 +81,19 @@ public $database = [
 
 **Deferred Writes**
 
-When `deferWrites` is enabled, multiple `set()` or `forget()` calls are batched into a single database transaction at the end of the request. This significantly reduces database queries:
+When `deferWrites` is enabled, multiple `set()` or `forget()` calls are batched and persisted in a single transaction at the end of the request. This significantly reduces database queries:
 
 ```php
-// With deferWrites = false: 3 separate queries (INSERT/UPDATE)
+// With deferWrites = false: 1 SELECT (hydrates all settings for context) + 3 separate INSERT/UPDATE queries
 $settings->set('Example.prop1', 'value1');
 $settings->set('Example.prop2', 'value2');
 $settings->set('Example.prop3', 'value3');
 
-// With deferWrites = true: 1 query updating 3 properties at the end of the request
+// With deferWrites = true: 1 SELECT + 1 INSERT batch + 1 UPDATE batch (all batched at end of request)
 ```
 
+The deferred approach is especially beneficial when updating existing records or performing many operations in a single request.
+
 ---
 
 ## FileHandler
@@ -123,14 +126,16 @@ public $file = [
 When `deferWrites` is enabled, multiple `set()` or `forget()` calls to the same class are batched into a single file write at the end of the request. This significantly reduces I/O operations:
 
 ```php
-// With deferWrites = false: 3 file writes
+// With deferWrites = false: 1 file read (hydrates all settings for class) + 3 separate file writes
 $settings->set('Example.prop1', 'value1');
 $settings->set('Example.prop2', 'value2');
 $settings->set('Example.prop3', 'value3');
 
-// With deferWrites = true: 1 file write at end of request
+// With deferWrites = true: 1 file read + 1 file write (all changes batched at end of request)
 ```
 
+The deferred approach is especially beneficial when updating multiple properties in the same class.
+
 ---
 
 ## ArrayHandler

docs/index.md

@@ -30,7 +30,7 @@ service('settings')->forget('App.siteName');
 ### Requirements
 
 ![PHP](https://img.shields.io/badge/PHP-%5E8.1-red)
-![CodeIgniter](https://img.shields.io/badge/CodeIgniter-%5E4.3-red)
+![CodeIgniter](https://img.shields.io/badge/CodeIgniter-%5E4.2.3-red)
 
 ### Acknowledgements
 

docs/limitations.md

@@ -3,13 +3,16 @@
 The following are known limitations of the library:
 
 1. **Immediate writes (`deferWrites => false`)**: Each setting is written to storage immediately when you call `set()` or `forget()`.
-   While `DatabaseHandler` and `FileHandler` use an in-memory cache to maintain fast reads, write operations happen one at a time,
-   which may result in multiple database queries or file writes per request.
+   The first operation hydrates all settings for that context (1 SELECT query), then each subsequent write performs a separate
+   INSERT or UPDATE. While `DatabaseHandler` and `FileHandler` use an in-memory cache to maintain fast reads, individual write
+   operations may result in multiple database queries or file writes per request.
 
 2. **Deferred writes (`deferWrites => true`)**: All settings are batched and written to storage at the end of the request
    (during the `post_system` event). This minimizes the number of database queries and file writes, improving performance.
-   However, this means write operations will not appear in CodeIgniter's Debug Toolbar, since the `post_system` event
-   executes after the toolbar data is collected.
+   However, there are important considerations:
+   - Write operations will not appear in CodeIgniter's Debug Toolbar, since the `post_system` event executes after toolbar data collection.
+   - If the request terminates early (fatal error, `exit()`, etc.) before `post_system`, pending writes are lost.
+   - Write failures are logged but handled silently - no exceptions are thrown back to the calling code.
 
 3. **First-level property access only**: You can only access the first level of a config property directly. In most config classes
    this is not an issue, since properties are simple values. However, some config files (like `Database`) contain properties that

src/Database/Migrations/2025-10-25-194218_AddUniqueKey.php

@@ -239,14 +239,20 @@ public function persistPendingProperties()
 
         $time = Time::now()->format('Y-m-d H:i:s');
 
-        // Separate deletes from upserts
+        // Separate deletes from upserts and prepare for database operations
         $deletes = [];
         $upserts = [];
 
         foreach ($this->pendingProperties as $info) {
             if ($info['delete']) {
-                $deletes[] = $info;
+                // Prepare delete row with correct database column names
+                $deletes[] = [
+                    'class'   => $info['class'],
+                    'key'     => $info['property'],
+                    'context' => $info['context'],
+                ];
             } else {
+                // Prepare upsert row with correct database column names
                 $upserts[] = [
                     'class'      => $info['class'],
                     'key'        => $info['property'],
@@ -262,31 +268,56 @@ public function persistPendingProperties()
         try {
             $this->db->transStart();
 
-            // Batch upsert all non-delete operations
+            // Handle upserts: fetch existing records matching our pending data
             if ($upserts !== []) {
-                $this->builder->upsertBatch($upserts);
-            }
+                // Build query to fetch only the specific records we need
+                $this->buildOrWhereConditions($upserts, 'class', 'key', 'context');
 
-            // Batch delete all delete operations
-            if ($deletes !== []) {
-                $this->builder->groupStart();
+                $existing = $this->builder->get()->getResultArray();
+
+                // Build a map of existing records for quick lookup
+                $existingMap = [];
+
+                foreach ($existing as $row) {
+                    $key               = $this->buildCompositeKey($row['class'], $row['key'], $row['context']);
+                    $existingMap[$key] = $row['id'];
+                }
 
-                foreach ($deletes as $i => $info) {
-                    if ($i > 0) {
-                        $this->builder->orGroupStart();
+                // Separate into inserts and updates
+                $inserts = [];
+                $updates = [];
+
+                foreach ($upserts as $row) {
+                    $key = $this->buildCompositeKey($row['class'], $row['key'], $row['context']);
+
+                    if (isset($existingMap[$key])) {
+                        // Record exists - prepare for update
+                        $updates[] = [
+                            'id'         => $existingMap[$key],
+                            'value'      => $row['value'],
+                            'type'       => $row['type'],
+                            'updated_at' => $row['updated_at'],
+                        ];
                     } else {
-                        $this->builder->groupStart();
+                        // New record - prepare for insert
+                        $inserts[] = $row;
                     }
+                }
 
-                    $this->builder
-                        ->where('class', $info['class'])
-                        ->where('key', $info['property'])
-                        ->where('context', $info['context']);
+                // Batch insert new records
+                if ($inserts !== []) {
+                    $this->builder->insertBatch($inserts);
+                }
 
-                    $this->builder->groupEnd();
+                // Batch update existing records
+                if ($updates !== []) {
+                    $this->builder->updateBatch($updates, 'id');
                 }
+            }
 
-                $this->builder->groupEnd();
+            // Batch delete all delete operations
+            if ($deletes !== []) {
+                $this->buildOrWhereConditions($deletes, 'class', 'key', 'context');
 
                 $this->builder->delete();
             }
@@ -295,13 +326,38 @@ public function persistPendingProperties()
 
             if ($this->db->transStatus() === false) {
                 log_message('error', 'Failed to persist pending properties to database.');
-
-                return;
             }
 
             $this->pendingProperties = [];
         } catch (DatabaseException $e) {
             log_message('error', 'Failed to persist pending properties: ' . $e->getMessage());
+
+            $this->pendingProperties = [];
+        }
+    }
+
+    /**
+     * Builds a composite key for lookup purposes.
+     */
+    private function buildCompositeKey(string $class, string $key, ?string $context): string
+    {
+        return $class . '::' . $key . ($context === null ? '' : '::' . $context);
+    }
+
+    /**
+     * Builds OR WHERE conditions for multiple rows.
+     */
+    private function buildOrWhereConditions(array $rows, string $classKey, string $keyKey, string $contextKey): void
+    {
+        foreach ($rows as $row) {
+            $this->builder->orGroupStart();
+
+            $this->builder
+                ->where($classKey, $row[$classKey])
+                ->where($keyKey, $row[$keyKey])
+                ->where($contextKey, $row[$contextKey]);
+
+            $this->builder->groupEnd();
         }
     }
 }