Crate aragog[−][src]
Aragog
aragog
is a fully featured ODM and OGM library for ArangoDB using the arangors driver.
The main concept is to provide behaviors allowing to map your structs with ArangoDB documents as simply an lightly as possible.
Inspired by Rails's Active Record library
aragog
aslo provides hooks and validations for your models.
The crate also provides a powerful AQL querying tool allowing complex and safe ArangoDB queries in Rust.
Migrations CLI
aragog
provides a safe schema generation and migrations command line interface: aragog_cli.
Features
By now the available features are:
- Creating a database connection pool from a defined
schema.yaml
(See aragog_cli) - Structures can implement different behaviors:
Record
: The structure can be written and retrieved as an ArangoDB collection document. This is the main trait for your modelsEdgeRecord
: The structure can be written and retrieved as an ArangoDB edge collection documentValidate
: The structure can perform simple validations before being created or saved into the database.Link
: The structure can define relations with other models based on defined queries.ForeignLink
: The structure can define relations with other models based on defined foreign key.
- Structures can also implement optional traits (disabled with the
minimal_traits
feature):Authenticate
: The structure can define a authentication behaviour from asecret
(a password for example)AuthorizeAction
: The structure can define authorization behavior on a target record with custom Action type.New
: The structure can be initialized from an other type (a form for example). It allows to maintain a privacy level in the model and to use different data formats.Update
: The structure can be updated from an other type (a form for example). It allows to maintain a privacy level in the model and to use different data formats.
- Different operations can return a
ServiceError
error that can easily be transformed into a Http Error (can be used for the actix framework) - Transactional operations
For detailed explanations on theses feature, read the book
Cargo features
Async and Blocking
By default all aragog
items are asynchronous, you can compile aragog
in a synchronous build using the blocking
feature:
aragog = { version = "0.10", features = ["blocking"], default-features = false }
You need to disable the default features. Don't forget to add the derive
feature to use the derive macros.
Actix and Open API
If you use this crate with the actix-web framework, you may want the aragog
errors to be usable as http errors.
To do so you can add to your cargo.toml
the following feature
: actix
. This will add Actix 3 dependency and compatibility
aragog = { version = "0.10", features = ["actix"] }
If you also want to be able to use paperclip, you may want aragog
elements to be compatible.
To do so you can add to your cargo.toml
the following feature
: open-api
.
aragog = { version = "0.10", features = ["actix", "open-api"] }
Password hashing
You may want aragog
to provide a more complete Authenticate
trait allowing to hash and verify passwords.
To do so you can add to your cargo.toml
the following feature
: password_hashing
.
aragog = { version = "0.10", features = ["password_hashing"] }
It will add two functions in the Authenticate
trait:
fn hash_password(password: &str, secret_key: &str) -> Result<String, ServiceError>; fn verify_password(password: &str, password_hash: &str, secret_key: &str) -> Result<(), ServiceError>;
hash_password
will return a Argon2 encrypted password hash you can safely store to your databaseverify_password
will check if the providedpassword
matches the Argon2 encrypted hash you stored.
The Argon2 encryption is based on the argonautica crate.
That crate requires the clang
lib, so if you deploy on docker you will need to install it or define a custom image.
Minimal Traits
If you don't need the following traits:
Authenticate
AuthorizeAction
New
Update
You can disable them with the minimal_traits
feature:
aragog = { version = "0.10", features = ["minimal_traits"] }
Schema and collections
In order for everything to work you need a schema.yaml
file. Use aragog_cli to create migrations and generate the file.
Creating a pool
To connect to the database and initialize a connection pool you may use the following builder pattern options:
let db_pool = DatabaseConnectionPool::builder() // You can specify a host and credentials with this method. // Otherwise, the builder will look for the env vars: `DB_HOST`, `DB_NAME`, `DB_USER` and `DB_PASSWORD`. .with_credentials("http://localhost:8529", "db", "user", "password") // You can specify a authentication mode between `Basic` and `Jwt` // Otherwise the default value will be used (`Basic`). .with_auth_mode(AuthMode::Basic) // You can specify a schema path to initialize the database pool // Otherwise the env var `SCHEMA_PATH` or the default value `config/db/schema.yaml` will be used. .with_schema_path("config/db/schema.yaml") // If you prefer you can use your own custom schema .with_schema(DatabaseSchema::default()) // The schema wil silently apply to the database, useful only if you don't use the CLI and migrations .apply_schema() // You then need to build the pool .build() .await .unwrap();
None of these options are mandatory.
Record
The global architecture is simple, every model you define that can be synced with the database must implement serde::Serialize
, serde::Deserialize
and Clone
.
To declare a struct
as a Model it must derive from aragog::Record
(the collection name must be the same as the struct) or implement it.
The final model structure will be an Exact representation of the content of a ArangoDB document, so without its _key
, _id
and _rev
.
Your project should contain some models
folder with every struct
representation of your database documents.
The real representation of a complete document is DatabaseRecord<T>
where T
is your model structure.
Example:
use aragog::{Record, DatabaseConnectionPool, DatabaseRecord, AuthMode}; use serde::{Serialize, Deserialize}; use tokio; #[derive(Serialize, Deserialize, Clone, Record)] pub struct User { pub username: String, pub first_name: String, pub last_name: String, pub age: usize } #[tokio::main] async fn main() { // Database connection Setup let database_pool = DatabaseConnectionPool::builder() .build() .await .unwrap(); // Define a document let mut user = User { username: String::from("LeRevenant1234"), first_name: String::from("Robert"), last_name: String::from("Surcouf"), age: 18 }; // user_record is a DatabaseRecord<User> let mut user_record = DatabaseRecord::create(user, &database_pool).await.unwrap(); // You can access and edit the document user_record.username = String::from("LeRevenant1524356"); // And directly save it user_record.save(&database_pool).await.unwrap(); }
Edge Record
You can declare Edge collection models by deriving from aragog::EdgeRecord
, the structure requires two string fields: _from
and _to
.
When deriving from EdgeRecord
the struct will also automatically derive from Record
so you'll need to implement Validate
as well.
Example:
#[derive(Serialize, Deserialize, Clone, Record)] pub struct Dish { pub name: String, pub price: usize } #[derive(Serialize, Deserialize, Clone, Record)] pub struct Order { pub name: String, } #[derive(Serialize, Deserialize, Clone, Record, EdgeRecord)] pub struct PartOf { pub _from: String, pub _to: String, } #[tokio::main] async fn main() { // Define a document let mut dish = DatabaseRecord::create(Dish { name: "Pizza".to_string(), price: 10, }, &database_pool).await.unwrap(); let mut order = DatabaseRecord::create(Order { name: "Order 1".to_string(), }, &database_pool).await.unwrap(); let edge = DatabaseRecord::link(&dish, &order, &database_pool, |_from, _to| { PartOf { _from, _to } }).await.unwrap(); assert_eq!(edge._from(), dish.id()); assert_eq!(edge._to(), order.id()); assert_eq!(&edge._from_key(), dish.key()); assert_eq!(&edge._to_key(), order.key()); }
Transactions
Aragog now supports transactional operations without API changes through the new Transaction
Object.
#[derive(Serialize, Deserialize, Clone, Record)] pub struct Dish { pub name: String, pub price: usize } #[tokio::main] async fn main() { let database_pool = DatabaseConnectionPool::builder() .build().await.unwrap(); // Instantiate a new transaction let transaction = Transaction::new(&database_pool).await.unwrap(); // Safely execute operations: let output = transaction.safe_execute(|transaction_pool| async move { // We use the provided `transaction_pool` instead of the classic pool DatabaseRecord::create(Dish { name: "Pizza".to_string(), price: 10, }, &transaction_pool).await?; DatabaseRecord::create(Dish { name: "Pasta".to_string(), price: 8, }, &transaction_pool).await?; DatabaseRecord::create(Dish { name: "Sandwich".to_string(), price: 5, }, &transaction_pool).await?; Ok(()) }).await.unwrap(); // The output allows to check the transaction state: Committed or Aborted assert!(output.is_committed()); }
If an operation fails in the safe_execute
block the transaction will be aborted and every operaiton cancelled.
Note: All the
DatabaseRecord
operation (create, save, link, etc) work as transactional, simply use the the provded transactionpool
instead of the classic pool
Querying
You can retrieve a document from the database as simply as it gets, from the unique ArangoDB _key
or from multiple conditions.
The example below show different ways to retrieve records, look at each function documentation for more exhaustive exaplanations.
Example
// User creation let record = DatabaseRecord::create(user, &database_pool).await.unwrap(); // Find with the primary key or.. let user_record = User::find(record.key(), &database_pool).await.unwrap(); // .. Generate a query and.. let query = User::query().filter(Filter::new(Comparison::field("last_name").equals_str("Surcouf")).and(Comparison::field("age").greater_than(15))); // get the only record (fails if no or multiple records) let user_record = User::get(query, &database_pool).await.unwrap().uniq().unwrap(); // Find all users with multiple conditions let query = User::query().filter(Filter::new(Comparison::field("last_name").like("%Surc%")).and(Comparison::field("age").in_array(&[15,16,17,18]))); let clone_query = query.clone(); // we clone the query // This syntax is valid... let user_records = User::get(query, &database_pool).await.unwrap(); // ... This one too let user_records = clone_query.call(&database_pool).await.unwrap().get_records::<User>();
You can simplify the previous queries with some tweaks and macros:
#[macro_use] extern crate aragog; let record = DatabaseRecord::create(user, &database_pool).await.unwrap(); // Find a user with a query let query = User::query().filter(compare!(field "last_name").equals_str("Surcouf").and(compare!(field "age").greater_than(15))); // get the only record (fails if no or multiple records) let user_record = User::get(query, &database_pool).await.unwrap().uniq().unwrap(); // Find all users with multiple conditions let query = User::query().filter(compare!(field "last_name").like("%Surc%").and(compare!(field "age").in_array(&[15,16,17,18]))); let clone_query = query.clone(); // This syntax is valid... let user_records = User::get(query, &database_pool).await.unwrap(); // ... This one too let user_records = clone_query.call(&database_pool).await.unwrap().get_records::<User>();
Query Object
You can intialize a query in the following ways:
Query::new("CollectionName")
Object.query()
(only works ifObject
implementsRecord
)query!("CollectionName")
You can customize the query with the following methods:
filter()
you can specify AQL comparisonsprune()
you can specify blocking AQL comparisons for traversal queriessort()
you can specify fields to sort withlimit()
you can skip and limit the query resultsdistinct()
you can skip duplicate documents
The order of operations will be respected in the rendered AQL query (except for
distinct
)
you can then call a query in the following ways:
query.call::<Object>(&database_connection_pool)
Object::get(query, &database_connection_pool
Which will return a JsonQueryResult
containing a Vec
of serde_json::Value
.
JsonQueryResult
can return deserialized models as DatabaseRecord
by calling .get_records::<T>()
Filter
You can initialize a Filter
with Filter::new(comparison)
Each comparison is a Comparison
struct built via ComparisonBuilder
:
// for a simple field comparison // Explicit Comparison::field("some_field").some_comparison("compared_value"); // Macro compare!(field "some_field").some_comparison("compared_value"); // for field arrays (see ArangoDB operators) // Explicit Comparison::all("some_field_array").some_comparison("compared_value"); // Macro compare!(all "some_field_array").some_comparison("compared_value"); // Explicit Comparison::any("some_field_array").some_comparison("compared_value"); // Macro compare!(any "some_field_array").some_comparison("compared_value"); // Explicit Comparison::none("some_field_array").some_comparison("compared_value"); // Macro compare!(none "some_field_array").some_comparison("compared_value");
All the currently implemented comparison methods are listed under ComparisonBuilder documentation page.
Filters can be defined explicitely like this:
let filter = Filter::new(Comparison::field("name").equals_str("felix"));
or
let filter :Filter = Comparison::field("name").equals_str("felix").into();
Traversal Querying
You can use graph features with sub-queries with different ways:
Straightforward Traversal query
- Explicit way
let query = Query::outbound(1, 2, "edgeCollection", "User/123"); let query = Query::inbound(1, 2, "edgeCollection", "User/123"); let query = Query::any(1, 2, "edgeCollection", "User/123"); // Named graph let query = Query::outbound_graph(1, 2, "NamedGraph", "User/123"); let query = Query::inbound_graph(1, 2, "NamedGraph", "User/123"); let query = Query::any_graph(1, 2, "NamedGraph", "User/123");
- Implicit way from a
DatabaseRecord<T>
let query = user_record.outbound_query(1, 2, "edgeCollection"); let query = user_record.inbound_query(1, 2, "edgeCollection"); // Named graph let query = user_record.outbound_graph(1, 2, "NamedGraph"); let query = user_record.inbound_graph(1, 2, "NamedGraph");
Sub queries
Queries can be joined together through
- Edge traversal:
let query = Query::new("User") .join_inbound(1, 2, false, Query::new("edgeCollection"));
- Named Graph traversal:
let query = Query::new("User") .join_inbound(1, 2, true, Query::new("SomeGraph"));
It works with complex queries:
let query = Query::new("User") .filter(Comparison::field("age").greater_than(10).into()) .join_inbound(1, 2, false, Query::new("edgeCollection") .sort("_key", None) .join_outbound(1, 5, true, Query::new("SomeGraph") .filter(Comparison::any("roles").like("%Manager%").into()) .distinct() ) );
Arango db setup
Installation (See official documentation Here)
- Download Link
- Run it with
/usr/local/sbin/arangod
The default installation contains one database_system
and a user namedroot
- Create a user and database for the project with the
arangosh
shell
arangosh> db._createDatabase("DB_NAME");
arangosh> var users = require("@arangodb/users");
arangosh> users.save("DB_USER", "DB_PASSWORD");
arangosh> users.grantDatabase("DB_USER", "DB_NAME");
It is a good practice to create a test db and a development db.
- you can connect to the new created db with
$> arangosh --server.username $DB_USER --server.database $DB_NAME
License
aragog
is provided under the MIT license. See LICENSE.
An simple lightweight ODM for ArangoDB based on arangors.
Re-exports
pub extern crate async_trait; |
pub use error::ServiceError; |
Modules
error | Error handling |
query | contains querying struct and functions. |
schema | Database schema construction utility, available for advanced development.
For classic usage use the |
transaction | The transaction module |
Macros
compare | Macro to simplify the |
query | Macro to simplify the |
Structs
DatabaseConnectionPool | Struct containing ArangoDB connections and information to access the database, collections and documents |
DatabaseRecord | Struct representing database stored documents. |
Enums
AuthMode | Defines which ArangoDB authentication mode will be used |
Traits
Authenticate | The |
AuthorizeAction | The |
DatabaseAccess | The |
EdgeRecord | Trait for structures that can be stored in Database as a ArangoDB EdgeCollection.
The trait must be implemented to be used as a edge record in |
ForeignLink | The |
Link | The |
New | The |
Record | The main trait of the Aragog library.
Trait for structures that can be stored in Database.
The trait must be implemented to be used as a record in |
Update | The |
Validate | The |