Add SurrealDB datasource support

docs/advanced-guide/injecting-databases-drivers/page.md

@@ -712,4 +712,136 @@ func queryDataPoints(c *gofr.Context) (any, error) {
 	}
 	return queryResp.QueryRespCnts, nil
 }
-```
+```
+
+## SurrealDB
+
+GoFr supports injecting SurrealDB database that supports the following interface. Any driver that implements the interface can be added
+using `app.AddSurrealDB()` method, and user's can use Surreal DB across application with `gofr.Context`.
+
+```go
+// SurrealDB defines an interface representing a SurrealDB client with common database operations.
+type SurrealDB interface {
+	// Query executes a Surreal query with the provided variables and returns the query results as a slice of interfaces.
+	// It returns an error if the query execution fails.
+	Query(ctx context.Context, query string, vars map[string]any) ([]any, error)
+
+	// Create inserts a new record into the specified table and returns the created record as a map.
+	// It returns an error if the operation fails.
+	Create(ctx context.Context, table string, data any) (map[any]any, error)
+
+	// Update modifies an existing record in the specified table by its ID with the provided data.
+	// It returns the updated record as an interface and an error if the operation fails.
+	Update(ctx context.Context, table string, id string, data any) (any, error)
+
+	// Delete removes a record from the specified table by its ID.
+	// It returns the result of the delete operation as an interface and an error if the operation fails.
+	Delete(ctx context.Context, table string, id string) (any, error)
+
+	// Select retrieves all records from the specified table.
+	// It returns a slice of maps representing the records and an error if the operation fails.
+	Select(ctx context.Context, table string) ([]map[string]any, error)
+}
+
+```
+
+Import the gofr's external driver for SurrealDB:
+
+```shell
+  go get gofr.dev/pkg/gofr/datasource/surrealdb
+```
+
+The following example demonstrates injecting an SurrealDB instance into a GoFr application.
+
+```go
+
+package main
+
+import (
+	"fmt"
+	"gofr.dev/pkg/gofr"
+	"gofr.dev/pkg/gofr/datasource/surrealdb"
+)
+
+type Person struct {
+	ID    string `json:"id,omitempty"`
+	Name  string `json:"name"`
+	Age   int    `json:"age"`
+	Email string `json:"email,omitempty"`
+}
+
+type ErrorResponse struct {
+	Message string `json:"message"`
+}
+
+func main() {
+	app := gofr.New()
+
+	client := surrealdb.New(&surrealdb.Config{
+		Host:       "localhost",
+		Port:       8000,
+		Username:   "root",
+		Password:   "root",
+		Namespace:  "test_namespace",
+		Database:   "test_database",
+		TLSEnabled: false,
+	})
+
+	app.AddSurrealDB(client)
+
+	// GET request to fetch person by ID
+	app.GET("/person/{id}", func(ctx *gofr.Context) (interface{}, error) {
+		id := ctx.PathParam("id")
+
+		query := "SELECT * FROM type::thing('person', $id)"
+		vars := map[string]interface{}{
+			"id": id,
+		}
+
+		result, err := ctx.SurrealDB.Query(ctx, query, vars)
+		if err != nil {
+			ctx.Logger.Error("Query error: ", err)
+			return nil, err
+		}
+
+		if len(result) > 0 {
+			return result[0], nil
+		}
+
+		return nil, fmt.Errorf("person not found")
+	})
+
+	// POST request to create a new person
+	app.POST("/person", func(ctx *gofr.Context) (interface{}, error) {
+		var person Person
+		if err := ctx.Bind(&person); err != nil {
+			ctx.Logger.Error("Binding error: ", err)
+			return ErrorResponse{Message: "Invalid request body"}, nil
+		}
+
+		result, err := ctx.SurrealDB.Create(ctx, "person", map[string]interface{}{
+			"name":  person.Name,
+			"age":   person.Age,
+			"email": person.Email,
+		})
+
+		if err != nil {
+			ctx.Logger.Errorf("Creation error: %v", err)
+			return ErrorResponse{Message: "Creation failed"}, nil
+		}
+
+		if id, ok := result["id"]; ok {
+			person.ID = fmt.Sprintf("%v", id)
+			return person, nil
+		}
+
+		return ErrorResponse{Message: "Unexpected result format"}, nil
+	})
+
+	app.Run()
+}
+
+
+```
+
+

pkg/gofr/container/container.go

@@ -59,6 +59,7 @@ type Container struct {
 	Solr       Solr
 	DGraph     Dgraph
 	OpenTSDB   OpenTSDB
+	SurrealDB  SurrealDB
 
 	KVStore KVStore
 

pkg/gofr/container/datasources.go

@@ -275,6 +275,40 @@ type MongoProvider interface {
 	provider
 }
 
+// SurrealDB defines an interface representing a SurrealDB client with common database operations.
+type SurrealDB interface {
+
+	// Query executes a Surreal query with the provided variables and returns the query results as a slice of interfaces.
+	// It returns an error if the query execution fails.
+	Query(ctx context.Context, query string, vars map[string]any) ([]any, error)
+
+	// Create inserts a new record into the specified table and returns the created record as a map.
+	// It returns an error if the operation fails.
+	Create(ctx context.Context, table string, data any) (map[string]any, error)
+
+	// Update modifies an existing record in the specified table by its ID with the provided data.
+	// It returns the updated record as an interface and an error if the operation fails.
+	Update(ctx context.Context, table string, id string, data any) (any, error)
+
+	// Delete removes a record from the specified table by its ID.
+	// It returns the result of the delete operation as an interface and an error if the operation fails.
+	Delete(ctx context.Context, table string, id string) (any, error)
+
+	// Select retrieves all records from the specified table.
+	// It returns a slice of maps representing the records and an error if the operation fails.
+	Select(ctx context.Context, table string) ([]map[string]any, error)
+
+	HealthChecker
+}
+
+// SurrealBDProvider is an interface that extends SurrealDB with additional methods for logging, metrics, or connection management.
+// It is typically used for initializing and managing SurrealDB-based data sources.
+type SurrealBDProvider interface {
+	SurrealDB
+
+	provider
+}
+
 type provider interface {
 	// UseLogger sets the logger for the Cassandra client.
 	UseLogger(logger any)

pkg/gofr/datasource/README.md

@@ -71,17 +71,18 @@ Therefore, GoFr utilizes a pluggable approach for new datasources by separating
 
 | Datasource       | Health-Check | Logs | Metrics | Traces | As Driver |
 |------------------|:------------:|:----:|:-------:|:------:|:---------:|
-| MySQL            | ✅          | ✅    | ✅    | ✅      |           |
-| REDIS            | ✅          | ✅    | ✅    | ✅      |           |
-| PostgreSQL       | ✅          | ✅    | ✅    | ✅      |           |
-| MongoDB          | ✅          | ✅    | ✅    |  ✅     | ✅         |
-| SQLite           | ✅          | ✅    | ✅    | ✅      |           |
-| BadgerDB         | ✅          | ✅    | ✅    |    ✅   | ✅         |
-| Cassandra        | ✅          | ✅    | ✅    |  ✅     | ✅         |
+| MySQL            | ✅          | ✅    | ✅    |   ✅    |           |
+| REDIS            | ✅          | ✅    | ✅    |   ✅    |           |
+| PostgreSQL       | ✅          | ✅    | ✅    |   ✅    |           |
+| MongoDB          | ✅          | ✅    | ✅    |   ✅    | ✅         |
+| SQLite           | ✅          | ✅    | ✅    |   ✅    |           |
+| BadgerDB         | ✅          | ✅    | ✅    |   ✅    | ✅         |
+| Cassandra        | ✅          | ✅    | ✅    |   ✅    | ✅         |
 | ClickHouse       |             | ✅    | ✅    |   ✅    | ✅         |
-| FTP              |             | ✅    |       |          | ✅         |
-| SFTP             |             | ✅    |       |          | ✅         |
+| FTP              |             | ✅    |       |        | ✅         |
+| SFTP             |             | ✅    |       |        | ✅         |
 | Solr             |             | ✅    | ✅    |   ✅    |   ✅      |
 | DGraph           | ✅          | ✅    | ✅    |   ✅    |           |
-| Azure Event Hubs |             | ✅    | ✅    |          |✅       |
+| Azure Event Hubs |             | ✅    | ✅    |        |✅       |
 | OpenTSDB         | ✅         | ✅     |       |   ✅    |   ✅     |
+| SurrealDB        | ✅         | ✅     |       |    ✅   |   ✅     |

pkg/gofr/datasource/surrealdb/go.mod

@@ -0,0 +1,23 @@
+module gofr.dev/pkg/gofr/datasource/surrealdb
+
+go 1.23.3
+
+require (
+	github.com/stretchr/testify v1.10.0
+	github.com/surrealdb/surrealdb.go v0.3.2
+	go.opentelemetry.io/otel v1.33.0
+	go.opentelemetry.io/otel/trace v1.33.0
+	go.uber.org/mock v0.5.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/fxamacker/cbor/v2 v2.7.0 // indirect
+	github.com/gofrs/uuid v4.4.0+incompatible // indirect
+	github.com/golang/groupcache v0.0.0-20200121045136-8c9f03a8e57e // indirect
+	github.com/gorilla/websocket v1.5.3 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	go.opencensus.io v0.24.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)