+## What is Georm?
Georm is a quite simple ORM built around
[SQLx](https://crates.io/crates/sqlx) that gives access to a few
useful functions when interacting with a database, implementing
automatically the most basic SQL interactions you’re tired of writing.
-
-
Why is Georm?
-
+## Why is Georm?
I wanted an ORM that’s easy and straightforward to use. I am aware
some other projects exist, such as
@@ -40,16 +38,12 @@ some other projects exist, such as
my needs and/or my wants of a simple interface. I ended up writing the
ORM I wanted to use.
-
-
How is Georm?
-
+## How is Georm?
I use it in a few projects, and I’m quite happy with it right now. But
of course, I’m open to constructive criticism and suggestions!
-
-
How can I use it?
-
+## How can I use it?
Georm works with SQLx, but does not re-export it itself. To get
started, install both Georm and SQLx in your Rust project:
@@ -121,9 +115,7 @@ pub struct Author {
Congratulations, your struct `Author` now has access to all the
functions described in the `Georm` trait!
-
-
Entity relationship
-
+## Entity relationship
It is possible to implement one-to-one, one-to-many, and many-to-many
relationships with Georm. This is a quick example of how a struct with
@@ -132,8 +124,12 @@ several relationships of different types may be declared:
#[derive(sqlx::FromRow, Georm)]
#[georm(
table = "books",
+ one_to_one = [
+ { name = "draft", remote_id = "book_id", table = "drafts", entity = Draft }
+ ],
one_to_many = [
- { name = "reviews", remote_id = "book_id", table = "reviews", entity = Review }
+ { name = "reviews", remote_id = "book_id", table = "reviews", entity = Review },
+ { name = "reprints", remote_id = "book_id", table = "reprints", entity = Reprint }
],
many_to_many = [{
name = "genres",
diff --git a/assets/logo.png b/assets/logo.png
new file mode 100644
index 0000000..8a4239f
Binary files /dev/null and b/assets/logo.png differ
diff --git a/assets/logo.svg b/assets/logo.svg
new file mode 100644
index 0000000..61b5e0a
--- /dev/null
+++ b/assets/logo.svg
@@ -0,0 +1,1272 @@
+
+
+
+
diff --git a/georm-macros/src/georm/ir.rs b/georm-macros/src/georm/ir.rs
deleted file mode 100644
index 9045db2..0000000
--- a/georm-macros/src/georm/ir.rs
+++ /dev/null
@@ -1,195 +0,0 @@
-use quote::quote;
-
-#[derive(deluxe::ExtractAttributes)]
-#[deluxe(attributes(georm))]
-pub struct GeormStructAttributes {
- pub table: String,
- #[deluxe(default = Vec::new())]
- pub one_to_many: Vec,
- #[deluxe(default = Vec::new())]
- pub many_to_many: Vec,
-}
-
-#[derive(deluxe::ParseMetaItem)]
-pub struct O2MRelationship {
- pub name: String,
- pub remote_id: String,
- pub table: String,
- pub entity: syn::Type,
-}
-
-impl From<&O2MRelationship> for proc_macro2::TokenStream {
- fn from(value: &O2MRelationship) -> Self {
- let query = format!(
- "SELECT * FROM {} WHERE {} = $1",
- value.table, value.remote_id
- );
- let entity = &value.entity;
- let function = syn::Ident::new(
- &format!("get_{}", value.name),
- proc_macro2::Span::call_site(),
- );
- quote! {
- pub async fn #function(&self, pool: &::sqlx::PgPool) -> ::sqlx::Result> {
- ::sqlx::query_as!(#entity, #query, self.get_id()).fetch_all(pool).await
- }
- }
- }
-}
-
-#[derive(deluxe::ParseMetaItem, Clone)]
-pub struct M2MLink {
- pub table: String,
- pub from: String,
- pub to: String,
-}
-
-#[derive(deluxe::ParseMetaItem)]
-pub struct M2MRelationship {
- pub name: String,
- pub entity: syn::Type,
- pub table: String,
- #[deluxe(default = String::from("id"))]
- pub remote_id: String,
- pub link: M2MLink,
-}
-
-pub struct Identifier {
- pub table: String,
- pub id: String,
-}
-
-pub struct M2MRelationshipComplete {
- pub name: String,
- pub entity: syn::Type,
- pub local: Identifier,
- pub remote: Identifier,
- pub link: M2MLink,
-}
-
-impl M2MRelationshipComplete {
- pub fn new(other: &M2MRelationship, local_table: &String, local_id: String) -> Self {
- Self {
- name: other.name.clone(),
- entity: other.entity.clone(),
- link: other.link.clone(),
- local: Identifier {
- table: local_table.to_string(),
- id: local_id,
- },
- remote: Identifier {
- table: other.table.clone(),
- id: other.remote_id.clone(),
- },
- }
- }
-}
-
-impl From<&M2MRelationshipComplete> for proc_macro2::TokenStream {
- fn from(value: &M2MRelationshipComplete) -> Self {
- let function = syn::Ident::new(
- &format!("get_{}", value.name),
- proc_macro2::Span::call_site(),
- );
- let entity = &value.entity;
- let query = format!(
- "SELECT remote.*
-FROM {} local
-JOIN {} link ON link.{} = local.{}
-JOIN {} remote ON link.{} = remote.{}
-WHERE local.{} = $1",
- value.local.table,
- value.link.table,
- value.link.from,
- value.local.id,
- value.remote.table,
- value.link.to,
- value.remote.id,
- value.local.id
- );
- quote! {
- pub async fn #function(&self, pool: &::sqlx::PgPool) -> ::sqlx::Result> {
- ::sqlx::query_as!(#entity, #query, self.get_id()).fetch_all(pool).await
- }
- }
- }
-}
-
-#[derive(deluxe::ExtractAttributes, Clone)]
-#[deluxe(attributes(georm))]
-struct GeormFieldAttributes {
- #[deluxe(default = false)]
- pub id: bool,
- #[deluxe(default = None)]
- pub relation: Option,
-}
-
-#[derive(deluxe::ParseMetaItem, Clone, Debug)]
-pub struct O2ORelationship {
- pub entity: syn::Type,
- pub table: String,
- #[deluxe(default = String::from("id"))]
- pub remote_id: String,
- #[deluxe(default = false)]
- pub nullable: bool,
- pub name: String,
-}
-
-#[derive(Clone, Debug)]
-pub struct GeormField {
- pub ident: syn::Ident,
- pub field: syn::Field,
- pub ty: syn::Type,
- pub id: bool,
- pub relation: Option,
-}
-
-impl GeormField {
- pub fn new(field: &mut syn::Field) -> Self {
- let ident = field.clone().ident.unwrap();
- let ty = field.clone().ty;
- let attrs: GeormFieldAttributes =
- deluxe::extract_attributes(field).expect("Could not extract attributes from field");
- let GeormFieldAttributes { id, relation } = attrs;
- Self {
- ident,
- field: field.to_owned(),
- id,
- ty,
- relation,
- }
- }
-}
-
-impl From<&GeormField> for proc_macro2::TokenStream {
- fn from(value: &GeormField) -> Self {
- let Some(relation) = value.relation.clone() else {
- return quote! {};
- };
- let function = syn::Ident::new(
- &format!("get_{}", relation.name),
- proc_macro2::Span::call_site(),
- );
- let entity = &relation.entity;
- let return_type = if relation.nullable {
- quote! { Option<#entity> }
- } else {
- quote! { #entity }
- };
- let query = format!(
- "SELECT * FROM {} WHERE {} = $1",
- relation.table, relation.remote_id
- );
- let local_ident = &value.field.ident;
- let fetch = if relation.nullable {
- quote! { fetch_optional }
- } else {
- quote! { fetch_one }
- };
- quote! {
- pub async fn #function(&self, pool: &::sqlx::PgPool) -> ::sqlx::Result<#return_type> {
- ::sqlx::query_as!(#entity, #query, self.#local_ident).#fetch(pool).await
- }
- }
- }
-}
diff --git a/georm-macros/src/georm/ir/m2m_relationship.rs b/georm-macros/src/georm/ir/m2m_relationship.rs
new file mode 100644
index 0000000..36091d5
--- /dev/null
+++ b/georm-macros/src/georm/ir/m2m_relationship.rs
@@ -0,0 +1,79 @@
+use quote::quote;
+
+#[derive(deluxe::ParseMetaItem, Clone)]
+pub struct M2MLink {
+ pub table: String,
+ pub from: String,
+ pub to: String,
+}
+
+#[derive(deluxe::ParseMetaItem)]
+pub struct M2MRelationship {
+ pub name: String,
+ pub entity: syn::Type,
+ pub table: String,
+ #[deluxe(default = String::from("id"))]
+ pub remote_id: String,
+ pub link: M2MLink,
+}
+
+pub struct Identifier {
+ pub table: String,
+ pub id: String,
+}
+
+pub struct M2MRelationshipComplete {
+ pub name: String,
+ pub entity: syn::Type,
+ pub local: Identifier,
+ pub remote: Identifier,
+ pub link: M2MLink,
+}
+
+impl M2MRelationshipComplete {
+ pub fn new(other: &M2MRelationship, local_table: &String, local_id: String) -> Self {
+ Self {
+ name: other.name.clone(),
+ entity: other.entity.clone(),
+ link: other.link.clone(),
+ local: Identifier {
+ table: local_table.to_string(),
+ id: local_id,
+ },
+ remote: Identifier {
+ table: other.table.clone(),
+ id: other.remote_id.clone(),
+ },
+ }
+ }
+}
+
+impl From<&M2MRelationshipComplete> for proc_macro2::TokenStream {
+ fn from(value: &M2MRelationshipComplete) -> Self {
+ let function = syn::Ident::new(
+ &format!("get_{}", value.name),
+ proc_macro2::Span::call_site(),
+ );
+ let entity = &value.entity;
+ let query = format!(
+ "SELECT remote.*
+FROM {} local
+JOIN {} link ON link.{} = local.{}
+JOIN {} remote ON link.{} = remote.{}
+WHERE local.{} = $1",
+ value.local.table,
+ value.link.table,
+ value.link.from,
+ value.local.id,
+ value.remote.table,
+ value.link.to,
+ value.remote.id,
+ value.local.id
+ );
+ quote! {
+ pub async fn #function(&self, pool: &::sqlx::PgPool) -> ::sqlx::Result> {
+ ::sqlx::query_as!(#entity, #query, self.get_id()).fetch_all(pool).await
+ }
+ }
+ }
+}
diff --git a/georm-macros/src/georm/ir/mod.rs b/georm-macros/src/georm/ir/mod.rs
new file mode 100644
index 0000000..84f61e8
--- /dev/null
+++ b/georm-macros/src/georm/ir/mod.rs
@@ -0,0 +1,98 @@
+use quote::quote;
+
+pub mod simple_relationship;
+use simple_relationship::{OneToMany, OneToOne, SimpleRelationship};
+
+pub mod m2m_relationship;
+use m2m_relationship::M2MRelationship;
+
+#[derive(deluxe::ExtractAttributes)]
+#[deluxe(attributes(georm))]
+pub struct GeormStructAttributes {
+ pub table: String,
+ #[deluxe(default = Vec::new())]
+ pub one_to_one: Vec>,
+ #[deluxe(default = Vec::new())]
+ pub one_to_many: Vec>,
+ #[deluxe(default = Vec::new())]
+ pub many_to_many: Vec,
+}
+
+#[derive(deluxe::ExtractAttributes, Clone)]
+#[deluxe(attributes(georm))]
+struct GeormFieldAttributes {
+ #[deluxe(default = false)]
+ pub id: bool,
+ #[deluxe(default = None)]
+ pub relation: Option,
+}
+
+#[derive(deluxe::ParseMetaItem, Clone, Debug)]
+pub struct O2ORelationship {
+ pub entity: syn::Type,
+ pub table: String,
+ #[deluxe(default = String::from("id"))]
+ pub remote_id: String,
+ #[deluxe(default = false)]
+ pub nullable: bool,
+ pub name: String,
+}
+
+#[derive(Clone, Debug)]
+pub struct GeormField {
+ pub ident: syn::Ident,
+ pub field: syn::Field,
+ pub ty: syn::Type,
+ pub id: bool,
+ pub relation: Option,
+}
+
+impl GeormField {
+ pub fn new(field: &mut syn::Field) -> Self {
+ let ident = field.clone().ident.unwrap();
+ let ty = field.clone().ty;
+ let attrs: GeormFieldAttributes =
+ deluxe::extract_attributes(field).expect("Could not extract attributes from field");
+ let GeormFieldAttributes { id, relation } = attrs;
+ Self {
+ ident,
+ field: field.to_owned(),
+ id,
+ ty,
+ relation,
+ }
+ }
+}
+
+impl From<&GeormField> for proc_macro2::TokenStream {
+ fn from(value: &GeormField) -> Self {
+ let Some(relation) = value.relation.clone() else {
+ return quote! {};
+ };
+ let function = syn::Ident::new(
+ &format!("get_{}", relation.name),
+ proc_macro2::Span::call_site(),
+ );
+ let entity = &relation.entity;
+ let return_type = if relation.nullable {
+ quote! { Option<#entity> }
+ } else {
+ quote! { #entity }
+ };
+ let query = format!(
+ "SELECT * FROM {} WHERE {} = $1",
+ relation.table, relation.remote_id
+ );
+ let local_ident = &value.field.ident;
+ let fetch = if relation.nullable {
+ quote! { fetch_optional }
+ } else {
+ quote! { fetch_one }
+ };
+ quote! {
+ pub async fn #function(&self, pool: &::sqlx::PgPool) -> ::sqlx::Result<#return_type> {
+ ::sqlx::query_as!(#entity, #query, self.#local_ident).#fetch(pool).await
+ }
+ }
+ }
+}
diff --git a/georm-macros/src/georm/ir/simple_relationship.rs b/georm-macros/src/georm/ir/simple_relationship.rs
new file mode 100644
index 0000000..5046068
--- /dev/null
+++ b/georm-macros/src/georm/ir/simple_relationship.rs
@@ -0,0 +1,66 @@
+use quote::quote;
+
+pub trait SimpleRelationshipType {}
+
+#[derive(deluxe::ParseMetaItem, Default)]
+pub struct OneToOne;
+impl SimpleRelationshipType for OneToOne {}
+
+#[derive(deluxe::ParseMetaItem, Default)]
+pub struct OneToMany;
+impl SimpleRelationshipType for OneToMany {}
+
+#[derive(deluxe::ParseMetaItem)]
+pub struct SimpleRelationship
+where
+ T: SimpleRelationshipType + deluxe::ParseMetaItem + Default,
+{
+ pub name: String,
+ pub remote_id: String,
+ pub table: String,
+ pub entity: syn::Type,
+ #[deluxe(default = T::default())]
+ _phantom: T,
+}
+
+impl SimpleRelationship
+where
+ T: SimpleRelationshipType + deluxe::ParseMetaItem + Default,
+{
+ pub fn make_query(&self) -> String {
+ format!("SELECT * FROM {} WHERE {} = $1", self.table, self.remote_id)
+ }
+
+ pub fn make_function_name(&self) -> syn::Ident {
+ syn::Ident::new(
+ &format!("get_{}", self.name),
+ proc_macro2::Span::call_site(),
+ )
+ }
+}
+
+impl From<&SimpleRelationship> for proc_macro2::TokenStream {
+ fn from(value: &SimpleRelationship) -> Self {
+ let query = value.make_query();
+ let entity = &value.entity;
+ let function = value.make_function_name();
+ quote! {
+ pub async fn #function(&self, pool: &::sqlx::PgPool) -> ::sqlx::Result> {
+ ::sqlx::query_as!(#entity, #query, self.get_id()).fetch_optional(pool).await
+ }
+ }
+ }
+}
+
+impl From<&SimpleRelationship> for proc_macro2::TokenStream {
+ fn from(value: &SimpleRelationship) -> Self {
+ let query = value.make_query();
+ let entity = &value.entity;
+ let function = value.make_function_name();
+ quote! {
+ pub async fn #function(&self, pool: &::sqlx::PgPool) -> ::sqlx::Result> {
+ ::sqlx::query_as!(#entity, #query, self.get_id()).fetch_all(pool).await
+ }
+ }
+ }
+}
diff --git a/georm-macros/src/georm/relationships.rs b/georm-macros/src/georm/relationships.rs
index f51c47b..0ac318c 100644
--- a/georm-macros/src/georm/relationships.rs
+++ b/georm-macros/src/georm/relationships.rs
@@ -1,6 +1,6 @@
use std::str::FromStr;
-use crate::georm::ir::M2MRelationshipComplete;
+use crate::georm::ir::m2m_relationship::M2MRelationshipComplete;
use super::ir::GeormField;
use proc_macro2::TokenStream;
@@ -15,16 +15,12 @@ fn join_token_streams(token_streams: &[TokenStream]) -> TokenStream {
.collect()
}
-fn derive(relationships: &[T], condition: P) -> TokenStream
+fn derive(relationships: &[T]) -> TokenStream
where
for<'a> &'a T: Into,
- P: FnMut(&&T) -> bool,
{
- let implementations: Vec = relationships
- .iter()
- .filter(condition)
- .map(std::convert::Into::into)
- .collect();
+ let implementations: Vec =
+ relationships.iter().map(std::convert::Into::into).collect();
join_token_streams(&implementations)
}
@@ -35,18 +31,20 @@ pub fn derive_relationships(
id: &GeormField,
) -> TokenStream {
let struct_name = &ast.ident;
- let one_to_one = derive(fields, |field| field.relation.is_some());
- let one_to_many = derive(&struct_attrs.one_to_many, |_| true);
+ let one_to_one_local = derive(fields);
+ let one_to_one_remote = derive(&struct_attrs.one_to_one);
+ let one_to_many = derive(&struct_attrs.one_to_many);
let many_to_many: Vec = struct_attrs
.many_to_many
.iter()
.map(|v| M2MRelationshipComplete::new(v, &struct_attrs.table, id.ident.to_string()))
.collect();
- let many_to_many = derive(&many_to_many, |_| true);
+ let many_to_many = derive(&many_to_many);
quote! {
impl #struct_name {
- #one_to_one
+ #one_to_one_local
+ #one_to_one_remote
#one_to_many
#many_to_many
}
diff --git a/src/lib.rs b/src/lib.rs
index 3a24a72..caa6b30 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -58,13 +58,13 @@
//!
//! Here is an explanation of what these different values mean:
//!
-//! | Value Name | Explanation | Default value |
-//! |------------|-----------------------------------------------------------------------------------------|---------------|
-//! | entity | Rust type of the entity found in the database | N/A |
+//! | Value Name | Explanation | Default value |
+//! |------------|------------------------------------------------------------------------------------------|---------------|
+//! | entity | Rust type of the entity found in the database | N/A |
//! | name | Name of the remote entity within the local entity; generates a method named `get_{name}` | N/A |
-//! | table | Database table where the entity is stored | N/A |
-//! | remote_id | Name of the column serving as the identifier of the entity | `"id"` |
-//! | nullable | Whether the relationship can be broken | `false` |
+//! | table | Database table where the entity is stored | N/A |
+//! | remote_id | Name of the column serving as the identifier of the entity | `"id"` |
+//! | nullable | Whether the relationship can be broken | `false` |
//!
//! Note that in this instance, the `remote_id` and `nullable` values can be
//! omitted as this is their default value. This below is a strict equivalent:
@@ -81,6 +81,39 @@
//! }
//! ```
//!
+//! But what if I have a one-to-one relationship with another entity and
+//! my current entity holds no data to reference that other identity? No
+//! worries, there is another way to declare such relationships.
+//!
+//! ```ignore
+//! #[georm(
+//! one_to_one = [{
+//! name = "profile",
+//! remote_id = "user_id",
+//! table = "profiles",
+//! entity = User
+//! }]
+//! )]
+//! struct User {
+//! #[georm(id)]
+//! id: i32,
+//! username: String,
+//! hashed_password: String,
+//! }
+//! ```
+//!
+//! We now have access to the method `User::get_profile(&self, &pool:
+//! sqlx::PgPool) -> Option`.
+//!
+//! Here is an explanation of the values of `one_to_many`:
+//!
+//! | Value Name | Explanaion | Default Value |
+//! |------------|------------------------------------------------------------------------------------------|---------------|
+//! | entity | Rust type of the entity found in the database | N/A |
+//! | name | Name of the remote entity within the local entity; generates a method named `get_{name}` | N/A |
+//! | table | Database table where the entity is stored | N/A |
+//! | remote_id | Name of the column serving as the identifier of the entity | `"id"` |
+//!
//! ## One-to-many relationships
//!
//! Sometimes, our entity is the one being referenced to by multiple entities,
@@ -105,7 +138,7 @@
//! entity = Post,
//! name = "posts",
//! table = "posts",
-//! remote_id = "id"
+//! remote_id = "author_id"
//! }]
//! )]
//! struct User {
diff --git a/tests/fixtures/simple_struct.sql b/tests/fixtures/simple_struct.sql
index e280e38..3da6929 100644
--- a/tests/fixtures/simple_struct.sql
+++ b/tests/fixtures/simple_struct.sql
@@ -1,6 +1,7 @@
INSERT INTO biographies (content)
VALUES ('Some text'),
- ('Some other text');
+ ('Some other text'),
+ ('Biography for no one');
INSERT INTO authors (name, biography_id)
VALUES ('J.R.R. Tolkien', 2),
diff --git a/tests/models.rs b/tests/models.rs
index 3fb7288..0e128cb 100644
--- a/tests/models.rs
+++ b/tests/models.rs
@@ -1,7 +1,12 @@
use georm::Georm;
#[derive(Debug, sqlx::FromRow, Georm, PartialEq, Eq, Default)]
-#[georm(table = "biographies")]
+#[georm(
+ table = "biographies",
+ one_to_one = [{
+ name = "author", remote_id = "biography_id", table = "authors", entity = Author
+ }]
+)]
pub struct Biography {
#[georm(id)]
pub id: i32,
diff --git a/tests/o2o_relationship.rs b/tests/o2o_relationship.rs
index ba74c05..426c36c 100644
--- a/tests/o2o_relationship.rs
+++ b/tests/o2o_relationship.rs
@@ -53,3 +53,24 @@ async fn books_are_found_despite_nonstandard_id_name(pool: sqlx::PgPool) -> sqlx
assert_eq!(tolkien, book.get_author(&pool).await?);
Ok(())
}
+
+#[sqlx::test(fixtures("simple_struct"))]
+async fn biographies_should_find_remote_o2o_author(pool: sqlx::PgPool) -> sqlx::Result<()> {
+ let london = Author::find(&pool, &3).await?.unwrap();
+ let london_biography = Biography::find(&pool, &1).await?.unwrap();
+ let result = london_biography.get_author(&pool).await;
+ assert!(result.is_ok());
+ let result = result.unwrap();
+ assert!(result.is_some());
+ let result = result.unwrap();
+ assert_eq!(london, result);
+ Ok(())
+}
+
+#[sqlx::test(fixtures("simple_struct"))]
+async fn biographies_may_not_have_corresponding_author(pool: sqlx::PgPool) -> sqlx::Result<()> {
+ let biography = Biography::find(&pool, &3).await?.unwrap();
+ let result = biography.get_author(&pool).await?;
+ assert!(result.is_none());
+ Ok(())
+}
+ 
