From d82f9fe2f473fed561f2502c2301c63bdd312c9c Mon Sep 17 00:00:00 2001 From: Lucien Cartier-Tilet Date: Sat, 1 Feb 2025 01:25:34 +0100 Subject: [PATCH] docs: update readme --- README.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 155 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4e4dd5a..05bde3b 100644 --- a/README.md +++ b/README.md @@ -1 +1,155 @@ -# Georm, a simple, opiniated SQLx ORM for PostgreSQL +

Georm

+
+ + A simple, opinionated SQLx ORM for PostgreSQL + +
+ +
+ +
+ + + actions status + + + Crates.io version + + + + docs.rs docs +
+ +
+

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?

+
+ +I wanted an ORM that’s easy and straightforward to use. I am aware +some other projects exist, such as +[SeaORM](https://www.sea-ql.org/SeaORM/), but they generally don’t fit +my needs and/or my wants of a simple interface. I ended up writing the +ORM I wanted to use. + +
+

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?

+
+ +Georm works with SQLx, but does not re-export it itself. To get +started, install both Georm and SQLx in your Rust project: + +```sh +cargo add sqlx --features postgres,macros # and any other feature you might want +cargo add georm +``` + +As Georm relies heavily on the macro +[`query_as!`](https://docs.rs/sqlx/latest/sqlx/macro.query_as.html), +the `macros` feature is not optional. Declare your tables in your +Postgres database (you may want to use SQLx’s `migrate` feature for +this), and then declare their equivalent in Rust. + +```sql +CREATE TABLE biographies ( + id SERIAL PRIMARY KEY, + content TEXT NOT NULL +); + +CREATE TABLE authors ( + id SERIAL PRIMARY KEY, + name VARCHAR(100) NOT NULL, + biography_id INT, + FOREIGN KEY (biography_id) REFERENCES biographies(id) +); +``` + +```rust +pub struct Author { + pub id: i32, + pub name: String, +} +``` + +To link a struct to a table in your database, derive the +`sqlx::FromRow` and the `georm::Georm` traits. +```rust +#[derive(sqlx::FromRow, Georm)] +pub struct Author { + pub id: i32, + pub name: String, +} +``` + +Now, indicate with the `georm` proc-macro which table they refer to. +```rust +#[derive(sqlx::FromRow, Georm)] +#[georm(table = "authors")] +pub struct Author { + pub id: i32, + pub name: String, +} +``` + +Finally, indicate with the same proc-macro which field of your struct +is the primary key in your database. +```rust +#[derive(sqlx::FromRow, Georm)] +#[georm(table = "authors")] +pub struct Author { + #[georm(id)] + pub id: i32, + pub name: String, +} +``` + +Congratulations, your struct `Author` now has access to all the +functions described in the `Georm` trait! + +
+

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 +several relationships of different types may be declared: +```rust +#[derive(sqlx::FromRow, Georm)] +#[georm( + table = "books", + one_to_many = [ + { name = "reviews", remote_id = "book_id", table = "reviews", entity = Review } + ], + many_to_many = [{ + name = "genres", + table = "genres", + entity = Genre, + link = { table = "book_genres", from = "book_id", to = "genre_id" } + }] +)] +pub struct Book { + #[georm(id)] + ident: i32, + title: String, + #[georm(relation = {entity = Author, table = "authors", name = "author"})] + author_id: i32, +} +``` + +To read more about these features, you can refer to the [online +documentation](https://docs.rs/sqlx/latest/georm/).