[FEATURE] Support SurrealDB

[nadmax]

Feature Description

Add support for interacting with SurrealDB through the Python SDK in Framefox.
This would enable developers to use SurrealDB, a serverless, document-graph database as a backend database option directly from their Python applications.

Problem Statement

Currently, Framefox lacks native support for SurrealDB via Python, limiting developers who want to leverage its capabilities like graph relations, embedded analytics, and flexible data modeling.
This makes it difficult for teams using SurrealDB to seamlessly integrate with Framefox’s data layer.

Proposed Solution

Integrate the official SurrealDB Python SDK into Framefox, allowing developers to:

• Connect to a SurrealDB instance
• Authenticate with credentials or tokens
• Perform CRUD operations
• Execute SurrealQL queries
• Handle real-time subscriptions (if applicable in future versions)

Alternatives Considered

• Using HTTP requests manually to communicate with SurrealDB’s REST/WebSocket endpoints. This is more error-prone and lacks the abstraction and convenience of an SDK.
• Using other databases supported by Framefox, but this may not suit use cases where SurrealDB's graph and hybrid document/relational model is required.

Implementation Details

• Add a new database adapter in Framefox to interface with the surrealdb Python package.
• Provide connection configuration through environment variables or config files (e.g., URL, namespace, database, user/pass).
• Abstract basic database operations (select, create, update, delete) in a reusable module.
• Optional: expose raw SurrealQL query execution for power users.

Example Usage

from framefox.db import get_surrealdb_client

db = get_surrealdb_client()

# authenticate
await db.signin({
    "user": "root",
    "pass": "root"
})

# use a specific namespace and database
await db.use("testns", "testdb")

# create a record
await db.create("person", {
    "name": "Alice",
    "age": 30
})

# query with SurrealQL
people = await db.query("SELECT * FROM person WHERE age > 25")

---

Benefits

• Enables use of a modern, flexible database suited for real-time and graph-oriented applications.
• Simplifies development by offering high-level access to SurrealDB capabilities through Python.
• Encourages broader backend choices for Framefox developers, especially in projects needing flexible schema and relationship modeling.

Additional Context

• SurrealDB provides a unified interface for document, relational, and graph data models.
• It supports querying via SurrealQL, a powerful SQL-like query language.
• The Python SDK provides async I/O and a clean API to interact with the database.

Checklist

Before submitting this feature request, I have:

• Checked that this feature hasn't already been proposed in existing issues
• Considered how this fits with Framefox's philosophy and architecture
• Thought about potential breaking changes or backward compatibility

[Abzac]

WTF is SurrealDB?

[nadmax]

WTF is SurrealDB?

It is a distributed, multi-model database written in Rust.
It is designed for real-time apps with built-in authentication, access control, and ACID transactions.
You don’t need a separate backend, SurrealDB can handle both your data and your app logic.

https://surrealdb.com/

[Abzac]

It is a distributed, multi-model database written in Rust.

Ah, it's written in Rust, well that explains everything then :)

[nadmax]

Ah, it's written in Rust, well that explains everything then :)

Not only for this reason!
You can check out the link above to see what SurrealDB is really built for.