Quick Start
Surreal ORM Documentation
Introduction
Surreal ORM is an Object-Relational Mapping and query-building library for Rust that provides a high-level API for interacting with SurrealDB, a distributed graph database. This documentation will guide you through the usage and features of the Surreal ORM library.
Getting Started
To use Surreal ORM in your Rust project, you need to add it as a dependency in
your Cargo.toml
file:
[dependencies]
surreal_orm = "https://github.com/Oyelowo/surreal_orm"
After adding the dependency, you can import the necessary modules in your Rust code:
Connecting to SurrealDB
Before interacting with SurrealDB, you need to establish a connection to the database. The following example demonstrates how to create a connection to a local SurrealDB instance:
use surrealdb::engine::local::Mem;
use surrealdb::Surreal;
#[tokio::main]
async fn main() {
let db = Surreal::new::<Mem>(()).await.unwrap();
}
In this example, we create a new SurrealDB instance using the Surreal::new
function with the local::Mem
engine. The local::Mem
engine represents a
local in-memory database. You can replace it with other engine types according
to your setup.
Defining a Model
A model in Surreal ORM represents a database table. You can define a model by
creating a Rust struct and implementing the Node
or Edge
trait. Here's an example of
defining a SpaceShip
model:
In this example, we define a SpaceShip
struct and annotate it with the Model
derive macro. The table
attribute specifies the name of the corresponding
database table.
Querying Data
Surreal ORM provides a fluent and expressive API for querying data from the
database. You can use the select
function to start a select statement and
chain various methods to build the query. Here's an example:
In this example, we start a select statement using the select
function and
pass the All
argument to select all fields. We specify the table name using
the from
method and add a condition using the where_
method. We can also use
the order_by
method to specify the sorting order and the limit
method to
limit the number of results.
Inserting Data
To insert data into the database, you can use the insert
function and provide
the data as a vector of structs. Here's an example:
In this example, we define a vector of SpaceShip
structs and pass it to the
insert
function. We then call the run
method to execute the insertion
operation.
Updating Data
To update data in the database, you can use the update
function and provide
the updated data as a struct. Here's an example:
In this example, we define a SpaceShip
struct with the updated data and pass
it to the update
function. We then call the run
method to execute the update
operation.
Deleting Data
To delete data from the database, you can use the delete
function and provide
the condition for deletion. Here's an example:
In this example, we use the delete
function and specify the table name as a
string. We add a condition using the where_
method, and then call the run
method to execute the deletion operation.
Conclusion
This concludes the basic usage and features of the Surreal ORM library. You can explore more advanced features and methods in the API documentation. If you have any further questions or need assistance, feel free to reach out.