feat: enhance README examples with error handling and advanced features

- Add comprehensive error handling examples with custom exceptions
- Include advanced JSON operations (length, type, ordering)
- Add query analysis examples (toSQL, describe)
- Include bulk operations with UPSERT handling
- Demonstrate exception context and retryable status
- All examples tested across MySQL, PostgreSQL, and SQLite

Author: tommyknocker

examples/07-readme-examples/01-readme-examples.php

@@ -235,4 +235,127 @@
     ]);
 echo "Updated age with modulo\n";
 
+echo "\n9. Error Handling Examples\n";
+echo "---------------------------\n";
+
+// Demonstrate exception handling
+try {
+    // This will work fine
+    $users = $db->find()->from('users')->get();
+    echo "Successfully retrieved " . count($users) . " users\n";
+    
+    // Try to insert duplicate email (will cause constraint violation)
+    $db->find()->table('users')->insert([
+        'name' => 'Duplicate User',
+        'email' => 'alice@example.com',  // This email already exists
+        'age' => 25
+    ]);
+} catch (\tommyknocker\pdodb\exceptions\ConstraintViolationException $e) {
+    echo "Constraint violation caught: " . $e->getMessage() . "\n";
+    echo "Constraint: " . $e->getConstraintName() . "\n";
+    echo "Table: " . $e->getTableName() . "\n";
+    echo "Retryable: " . ($e->isRetryable() ? 'Yes' : 'No') . "\n";
+} catch (\tommyknocker\pdodb\exceptions\DatabaseException $e) {
+    echo "Database error caught: " . $e->getMessage() . "\n";
+    echo "Driver: " . $e->getDriver() . "\n";
+    echo "Category: " . $e->getCategory() . "\n";
+}
+
+// Demonstrate error context
+try {
+    // Try invalid query
+    $db->find()->from('nonexistent_table')->get();
+} catch (\tommyknocker\pdodb\exceptions\QueryException $e) {
+    echo "Query error caught: " . $e->getMessage() . "\n";
+    echo "Query: " . $e->getQuery() . "\n";
+    echo "Context: " . json_encode($e->getContext()) . "\n";
+}
+
+echo "\n10. Advanced JSON Operations\n";
+echo "-----------------------------\n";
+
+// JSON length and type
+$jsonUsers = $db->find()
+    ->from('users')
+    ->select([
+        'id',
+        'name',
+        'tag_count' => Db::jsonLength('tags'),
+        'tags_type' => Db::jsonType('tags')
+    ])
+    ->where(Db::jsonLength('tags'), 2, '>')
+    ->get();
+echo "Users with more than 2 tags: " . count($jsonUsers) . "\n";
+
+// JSON ordering
+$sortedByAge = $db->find()
+    ->from('users')
+    ->orderBy(Db::jsonGet('meta', ['age']), 'DESC')
+    ->where(Db::jsonExists('meta', ['age']))
+    ->get();
+echo "Users sorted by JSON age: " . count($sortedByAge) . "\n";
+
+echo "\n11. Query Analysis Examples\n";
+echo "---------------------------\n";
+
+// Get SQL without execution
+$query = $db->find()
+    ->table('users')
+    ->where('age', 25, '>')
+    ->andWhere('status', 'active')
+    ->toSQL();
+echo "Generated SQL: " . $query['sql'] . "\n";
+echo "Parameters: " . json_encode($query['params']) . "\n";
+
+// Table structure analysis
+$structure = $db->find()->table('users')->describe();
+echo "Table structure columns: " . count($structure) . "\n";
+
+echo "\n12. Bulk Operations\n";
+echo "------------------\n";
+
+// UPSERT example (works differently on SQLite)
+try {
+    $upsertResult = $db->find()->table('users')->onDuplicate([
+        'age' => Db::inc(),
+        'updated_at' => Db::now()
+    ])->insert([
+        'email' => 'upsert@example.com',
+        'name' => 'Upsert User',
+        'age' => 30
+    ]);
+    echo "UPSERT result: " . $upsertResult . "\n";
+} catch (\Exception $e) {
+    // SQLite doesn't support ON DUPLICATE KEY UPDATE, so we'll do a manual upsert
+    $existing = $db->find()
+        ->from('users')
+        ->where('email', 'upsert@example.com')
+        ->getOne();
+    
+    if ($existing) {
+        $db->find()
+            ->table('users')
+            ->where('email', 'upsert@example.com')
+            ->update([
+                'age' => Db::inc(),
+                'updated_at' => Db::now()
+            ]);
+        echo "Updated existing user\n";
+    } else {
+        $db->find()->table('users')->insert([
+            'email' => 'upsert@example.com',
+            'name' => 'Upsert User',
+            'age' => 30
+        ]);
+        echo "Inserted new user\n";
+    }
+}
+
+// Check if user exists after upsert
+$exists = $db->find()
+    ->from('users')
+    ->where('email', 'upsert@example.com')
+    ->exists();
+echo "User exists after upsert: " . ($exists ? 'Yes' : 'No') . "\n";
+
 echo "\n=== Demo Complete ===\n";