Add database sql resilience example

Author: Mak-1911

examples/sql/README.md

@@ -0,0 +1,37 @@
+# SQL Example
+
+This example demonstrates how to use Resile with Go's standard `database/sql` package.
+
+It wraps `db.ExecContext` call with retries and a circuit breaker. The example uses a mock SQL driver instead of a real database so it can run anywhere without extra setup. 
+
+The mock driver fails the first two attempts with a temporary error and succeeds on the third attempt. This shows Resile retrying the operation.
+
+## Run
+```bash
+go run ./examples/sql                                                     
+```
+Expected output:                                                          
+```
+query succeeded after 3 attempts; rows affected: 1                        
+```                                                                         
+## How It Works
+```go
+result, err := resile.Do(ctx, func(ctx context.Context) (sql.Result, error) {
+        return db.ExecContext(ctx, "UPDATE users SET active = ? WHERE id = ?",
+        true, 
+        42
+    )
+  },                                                                        
+        resile.WithRetry(3),                                                
+        resile.WithBaseDelay(100*time.Millisecond),                         
+        resile.WithCircuitBreaker(breaker),                                 
+)
+```                 
+
+The SQL call is wrapped with `resile.Do`. 
+The circuit breaker is included to show how you can stop calling a database when repeated failures suggest it is unhealthy.
+
+## Note about SQL Writes
+Be careful when retrying write queries like UPDATE, INSERT, or DELETE.
+A retry in this case will run the same write more than once if the first attempt has reached the database but client received no response. In production applications, transactions, idempotency keys, unique constraints, or other safeguards are employed when retrying writes.
+

examples/sql/main.go

@@ -0,0 +1,81 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"database/sql/driver"
+	"errors"
+	"fmt"
+	"github.com/cinar/resile"
+	"github.com/cinar/resile/circuit"
+	"sync/atomic"
+	"time"
+)
+
+var attempts atomic.Int32
+
+// transientFailureDriver is a mock SQL driver that fails the first two calls.
+type transientFailureDriver struct{}
+type transientFailureConnection struct{}
+
+func (transientFailureDriver) Open(name string) (driver.Conn, error) {
+	return transientFailureConnection{}, nil
+}
+
+func (transientFailureConnection) Prepare(query string) (driver.Stmt, error) {
+	return nil, errors.New("Prepare is not implemented")
+}
+
+func (transientFailureConnection) Begin() (driver.Tx, error) {
+	return nil, errors.New("transactions are not implemented")
+}
+
+func (transientFailureConnection) Close() error {
+	return nil
+}
+
+func (transientFailureConnection) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Result, error) {
+	current := attempts.Add(1)
+	if current < 3 {
+		return nil, errors.New("temporary database error")
+	}
+	return driver.RowsAffected(1), nil
+}
+
+func main() {
+	sql.Register("transient-sql", transientFailureDriver{})
+
+	db, err := sql.Open("transient-sql", "")
+	if err != nil {
+		panic(err)
+	}
+	defer db.Close()
+
+	ctx := context.Background()
+
+	breaker := circuit.New(circuit.Config{
+		WindowType:           circuit.WindowCountBased,
+		WindowSize:           10,
+		MinimumCalls:         3,
+		FailureRateThreshold: 50,
+		ResetTimeout:         time.Second,
+	})
+
+	// SQL call wrapped with Resile so transient db errors can be retried
+	result, err := resile.Do(ctx, func(ctx context.Context) (sql.Result, error) {
+		return db.ExecContext(ctx, "UPDATE users SET active = ? WHERE id = ?", true, 42)
+	},
+		resile.WithRetry(3),
+		resile.WithBaseDelay(100*time.Millisecond),
+		resile.WithCircuitBreaker(breaker),
+	)
+
+	if err != nil {
+		fmt.Printf("query failed: %v\n", err)
+		return
+	}
+
+	rowsAffected, _ := result.RowsAffected()
+	fmt.Printf("query succeeded after %d attempts; rows affected: %d\n",
+		attempts.Load(), rowsAffected)
+}