Omi - Object Mapping Intelligently
A library that maps object structures to relational databases and provides interfaces for common queries and updates.
Install
Omi is under active development and when adding a dependency you will need to add it via the git repository method like the following:
# Cargo.toml
[dependencies]
omi = { git = "https://github.com/amphitheatre-app/omi" }
Getting Started
Let's start with a quick preview of some of Omi's main current features, which will be updated here and in possible future special documents as they become available, so stay tuned!
Entity definition
use omi::prelude::*
#[entity(table = "products")]
#[derive(Entity, Queryable, Creatable, Updatable, Deletable)]
pub struct Product {
/// Auto incremented primary key
#[column(primary, auto, null)]
id: u64,
/// The title of product
#[column(length = 255, default = "")]
title: String
/// The brand of this product
#[relation(belongs_to)]
brand: Brand,
/// Has many reviews
#[relation(has_many)
reviews: Vec<Review>,
}
Querying
Using the one() method allows you to retrieve a single record without setting any filter conditions, which is equivalent to "SELECT * FROM products offset 0 limit 1". Of course, you can also specify filter fields:
Product::find().one(db);
Typically, we use the all() method to get multiple rows, which will query the database based on the filters you submit, the equivalent SQL is SELECT * FROM products.
Product::find().all(db);
Omi's filter() method provides a more advanced filtering capability, where you can simply enter a tuple, or a vector of combinations of conditions:
// SQL: SELECT * FROM products WHERE id=123
Product::find().filter(("id", 123)).all(db);
// SQL: SELECT * FROM products WHERE foo=123 AND bar=456
Product::find()
.filter([("foo", 123), ("bar", 456)])
.all(db);
Omi can also be more advanced conditional expressions to support AND, OR filtering, the equivalent SQL is SELECT * FROM products WHERE (title like "*abc" AND brand_id=123) OR (title like "*xyz" AND brand_id=456).
Product::find()
.filter(
Or(
And([("title", "*abc"), ("brand_id", 123)]),
And([("title", "*xyz"), ("brand_id", 456)]),
)
)
.all(db);
The order_by() method takes a tuple vector to specify the field or multiple field to be sorted and the direction.
use crate::order::Direction::Desc;
// single field
Product::find()
.filter(("id", 123))
.order_by([("id", Desc)])
.all(db);
// multiple fields
Product::find()
.filter(("id", 123))
.order_by([("id", Desc), ("id", Desc)])
.all(db);
And the group by operation is similar.
Product::find().group_by(["brand_id", "status"]).all(db);
Finally, the offset and limit limits are essential for query statements
Product::find().offset(0).limit(20).all(db);
Create
Create an instance of your entity and simply call the create() method to insert a new record into the database:
Product::create(product).execute(db);
Update
The first way is to make changes to the instance and then call the update() method to update it. Omi will automatically recognize the model of this instance and compare the differences, saving only the changed part of the fields to the database.
Product::update(Some(product)).execute(db);
Of course, you can also call the update() method to update the specified fields raw, which eliminates the need for prior data loading, reduces the number of database reads, and, in certain cases, optimizes the processing speed of the application.
// single field
Product::update(None)
.filter(("id", 123))
.set("title", "abc")
.execute(db);
// multiple fields
Product::update(None)
.filter(("id", 123))
.set([("title", "abc"), ("brand_id", "456")])
.execute(db);
Delete
Product::delete(product).execute(db);
Relations
You can call the include() or exclude() methods to include or exclude associated objects, and by default all associated data for this model will be included.
Product::find().filter(("id", 123)).include(["reviews"]).one(db);
Product::find().filter(("id", 123)).exclude(["reviews"]).one(db);
Transaction
omi::transaction::start();
omi::transaction::rollback();
omi::transaction::commit();
Raw queries
You can use the raw() method for edge cases where existing mechanisms or interfaces don't meet your needs, and it will still provide you with object mapping support.
omi::raw::<Product>(
format!("SELECT * FROM products where id = {}", 123)
).execute(db);
Contributing
If anything feels off, or if you feel that some functionality is missing, please check out the contributing page. There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.
License
Omi is licensed under Apache License 2.0. See LICENSE for more information.
2.3k Jan 1, 2023
30 Sep 7, 2022
1.9k Dec 28, 2022
23 Nov 11, 2022
13 Feb 17, 2022
3 Nov 14, 2021
156 Dec 30, 2022
4 Aug 19, 2022
37 Dec 27, 2022
1 Dec 23, 2021
4 Jun 3, 2022
2 May 13, 2022
1 Jan 3, 2022
2 Jun 12, 2022
6 Jun 13, 2022
215 Dec 30, 2022
2 Jun 11, 2022
71 Dec 28, 2022
7 Aug 29, 2022
23 Nov 11, 2022
3 Aug 5, 2022
116 Jan 2, 2023
31.5k Jan 1, 2023
208 Dec 27, 2022
2 Dec 14, 2022
10 Dec 28, 2022
2 Dec 15, 2022
5 Jul 5, 2023
7 Aug 31, 2023