Aragog
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
Features
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 asecret
(a password for example) (seepassword_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)
Cargo features
Actix Http Error
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
.
= { = "^0.5", = ["actix_http_error"] }
Password hashing
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
.
= { = "^0.5", = ["password_hashing"] }
It will add two functions in the Authenticate
trait:
;
;
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.
Schema and collections
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.json
file in /examples/simple_food_order_app
The json must look like this:
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
Indexes
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.
Database Record
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:
use ;
use ;
use tokio;
async
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 explanations.
Example
// User creation
let record = create.await.unwrap;
// Find with the primary key or..
let user_record = find.await.unwrap;
// .. Generate a query and..
let query = query.filter;
// get the only record (fails if no or multiple records)
let user_record = get.await.unwrap.uniq.unwrap;
// Find all users with multiple conditions
let query = query.filter;
let clone_query = query.clone; // we clone the query
// This syntax is valid...
let user_records = get.await.unwrap;
// ... This one too
let user_records = clone_query..await.unwrap;
You can simplify the previous queries with some macros:
extern crate aragog;
// Find a user with multiple conditions
let query = query!.filter;
let records = get.await.unwrap;
The querying system hierarchy works this way:
.filter.and.or.sort.limit.distinct;
new
Query
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 comparisonssort()
you can specify fields to sort withlimit()
you can skip and limit the query resultsdistinct()
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()
.
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
field.some_comparison;
// Macro
compare!.some_comparison;
// for field arrays (see ArangoDB operators)
// Explicit
all.some_comparison;
// Macro
compare!.some_comparison;
// Explicit
any.some_comparison;
// Macro
compare!.some_comparison;
// Explicit
none.some_comparison;
// Macro
compare!.some_comparison;
All the currently implemented comparison methods are listed under ComparisonBuilder documentation page.
TODO
- Query system:
- Simple and modular query system
- Advanced query system supporting:
- Array variant querying (
ANY
,NONE
,ALL
) - Sort, limit and distinct methods
- Macros for syntax simplification
- ArangoDB functions (
LENGTH
,ABS
, etc.)
- Array variant querying (
- ORM and OGM
- Pundit like authorizations (authorize actions on model)
- Relations
- Handle graph vertices and edges
- Handle SQL-like relations (foreign keys)
- Handle key-value pair system (redis like)
- Middle and long term:
- Handle revisions/concurrency correctly
- Code Generation
- Avoid string literals as collection names
- Handle Migrations
- Define possible
async
validations for database advance state check
Arango db setup
Installation (See official documentation [Here] arango_doc)
- 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.