aragog is a simple lightweight ODM library for ArangoDB using the arangors driver.
The main concept is to provide behaviors allowing to synchronize documents and structs as simply an lightly as possible.
In the future versions aragog will also be able to act as a ORM and OGM for ArangoDB
By now the available features are:
* Creating a database connection pool from a defined schema.json
* Structures can implement different behaviors:
* Record: The structure can be written into a ArangoDB collection as well as retrieved, from its _key or other query arguments.
* 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.
* Validate: The structure can perform simple validations before being created or saved into the database.
* Authenticate: The structure can define a authentication behaviour from a secret (a password for example) (see password_hashing section)
* AuthorizeAction: The structure can define authorization behavior on a target record with custom Action type.
* Different operations can return a ServiceError error that can easily be transformed into a Http Error (can be used for the actix framework)
If you use this crate with the actix framework, you may want the aragog errors to be usable as http errors.
To do so cou can add to your cargo.toml the following feature: actix_http_error.
toml
aragog = { version = "^0.5", features = ["actix_http_error"] }
You may want aragog to provide a more complete Authenticate trait allowing to hash and verify passwords.
To do so cou can add to your cargo.toml the following feature: password_hashing.
toml
aragog = { version = "^0.5", features = ["password_hashing"] }
It will add two functions in the Authenticate trait:
rust
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 database
* verify_password will check if the provided password 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.
In order for everything yo work you need to specify a schema.json file. The path of the schema must be set in SCHEMA_PATH environment variable or by default the pool will look for it in src/config/db/schema.json.
There is an example
schema.jsonfile in /examples/simplefoodorder_app
The json must look like this:
json
{
"collections": [
{
"name": "collection1",
"indexes": []
},
{
"name": "collection2",
"indexes": [
{
"name": "byUsernameAndEmail",
"fields": ["username", "email"],
"settings": {
"type": "persistent",
"unique": true,
"sparse": false,
"deduplicate": false
}
}
]
}
]
}
When initializing the DatabaseConnectionPool every collection name will be searched in the database and if not found the collection will be automatically created.
You don't need to create the collections yourself
The array of Index in indexes must have that exact format:
* name: the index name,
* fields: an array of the fields concerned on that compound index,
* settings: this json bloc must be the serialized version of an IndexSettings variant from arangors driver.
The global architecture is simple, every Model you define that can be synced with the database must implement Record and derive from serde::Serialize, serde::Deserialize and Clone.
If you want any of the other behaviors you can implement the associated trait
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:
```rust use aragog::{Record, DatabaseConnectionPool, DatabaseRecord, Validate}; use serde::{Serialize, Deserialize}; use tokio;
pub struct User { pub username: String, pub firstname: String, pub lastname: String, pub age: usize }
impl Record for User { fn collection_name() -> &'static str { "Users" } }
impl Validate for User {
fn validations(&self,errors: &mut Vec
async fn main() {
// Database connection Setup
let databasepool = DatabaseConnectionPool::new("http://localhost:8529", "db", "user", "password").await;
// Define a document
let mut user = User {
username: String::from("LeRevenant1234"),
firstname: String::from("Robert"),
lastname: String::from("Surcouf"),
age: 18
};
// userrecord is a DatabaseRecord
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 explanations.
Example ```rust // User creation let record = DatabaseRecord::create(user, &databasepool).await.unwrap(); // Find with the primary key or.. let userrecord = User::find(&record.key, &databasepool).await.unwrap(); // .. Generate a query and.. let query = User::query().filter(Filter::new(Comparison::field("lastname").equalsstr("Surcouf")).and(Comparison::field("age").greaterthan(15))); // get the only record (fails if no or multiple records) let userrecord = User::get(query, &databasepool).await.unwrap().uniq().unwrap();
// Find all users with multiple conditions
let query = User::query().filter(Filter::new(Comparison::field("lastname").like("%Surc%")).and(Comparison::field("age").inarray(&[15,16,17,18])));
let clonequery = query.clone(); // we clone the query
// This syntax is valid...
let userrecords = User::get(query, &databasepool).await.unwrap();
// ... This one too
let userrecords = clonequery.call::
You can simplify the previous queries with some macros: ```rust
// Find a user with multiple conditions let query = query!("Users").filter(Filter::new(compare!(field "lastname").equalsstr("Surcouf")).and(compare!(field "age").greaterthan(15))); let records = User::get(query, &databasepool).await.unwrap(); ```
The querying system hierarchy works this way:
rust
Query::new("collection_name").filter(comparison_1).and(comparison_2).or(comparison_3).sort().limit().distinct();
You can intialize a query in the following ways:
* Query::new("CollectionName")
* Object.query() (only works if Object implements Record)
* query!("CollectionName")
You can customize the query with the following methods:
* filter() you can specify AQL comparisons
* sort() you can specify fields to sort with
* limit() you can skip and limit the query results
* distinct() you can skip duplicate documents
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 QueryResult containing a Vec of DatabaseRecord<Object>.
If you want to receive a unique record and render an error in case of multiple record you can use uniq().
You can initialize a Filter with Filter::new(comparison)
Each comparison is a Comparison struct built via ComparisonBuilder:
```rust
// for a simple field comparison
// Explicit Comparison::field("somefield").somecomparison("comparedvalue"); // Macro compare!(field "somefield").somecomparison("comparedvalue");
// for field arrays (see ArangoDB operators)
// Explicit Comparison::all("somefieldarray").somecomparison("comparedvalue"); // Macro compare!(all "somefieldarray").somecomparison("comparedvalue");
// Explicit Comparison::any("somefieldarray").somecomparison("comparedvalue"); // Macro compare!(any "somefieldarray").somecomparison("comparedvalue");
// Explicit Comparison::none("somefieldarray").somecomparison("comparedvalue"); // Macro compare!(none "somefieldarray").somecomparison("comparedvalue"); ``` All the currently implemented comparison methods are listed under ComparisonBuilder documentation page.
ANY, NONE, ALL)LENGTH, ABS, etc.)async validations for database advance state checkInstallation (See official documentation Here)
/usr/local/sbin/arangod The default installation contains one database _system and a user named rootarangosh 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.
$> arangosh --server.username $DB_USER --server.database $DB_NAME
aragog is provided under the MIT license. See LICENSE.
An simple lightweight ODM for ArangoDB based on arangors.