`🌍 Atmosphere`

A lightweight sql framework for sustainable database reliant systems

</div>

Overview

Atmosphere is a lightweight SQL framework designed for sustainable, database-reliant systems. It leverages Rust's powerful type and macro systems to derive SQL schemas from your rust struct definitions into an advanced trait system.

Key Features

SQL schema derivation from Rust structs.
Advanced trait system for query generation.
Automated database code testing with atmosphere::testing
ORM-like CRUD traits.
Code reusability across API layers using generics.
Compile-time introspection for type-safe schema generation.

Quickstart

use atmosphere::prelude::*;

#[table(schema = "public", name = "user")]
struct User {
    #[sql(pk)]
    id: i32,
    name: String,
    #[sql(unique)]
    email: String,
}

#[table(schema = "public", name = "post")]
struct Post {
    #[sql(pk)]
    id: i32,
    #[sql(fk -> User, rename = "author_id")]
    author: i32,
    #[sql(unique)]
    title: String,
}

#[tokio::main]
async fn main() -> sqlx::Result<()> {
    let pool = atmosphere::Pool::connect(&std::env::var("DATABASE_URL").unwrap()).await?;

    // CRUD operations

    let user = User { id: 0, name: "demo".to_owned(), email: "some@email.com".to_owned(), };

    user.save(&pool).await?;
    user.delete(&pool).await?;
    user.create(&pool).await?;

    // Field Queries

    assert_eq!(
        User::read(&pool, &0).await?,
        User::find_by_email(&pool, "some@email.com").await?.unwrap()
    );

    // Relationships

    Post { id: 0, author: 0, title: "test".to_owned() }
        .save(&pool)
        .await?;

    Post::find_by_author(&pool, &0).await?;
    Post::delete_by_author(&pool, &0).await?;

    // Inter-Table Operations

    Post { id: 1, author: 0, title: "test1".to_owned() }
        .author(&pool).await?;

    user.posts(&pool).await?;
    user.delete_posts(&pool).await?;

    Ok(())
}

Atmosphere introspects the User and Post structs at compile time and generates const available type information about the schema into the Table trait.

Roadmap

Alpha Release

[x] Advanced SQL Trait System (Table, Column, Relation ..)
[x] SQL Field Attributes (#[sql(pk)], #[sql(fk -> Model)] and so on)
[x] SQL Query Generation
[x] Automated Integration Testing
[x] Attribute Macro (#[table])

Beta Release

[x] Transaction Support
[x] Getting Database Agnostic
[x] Hook into query execution using atmosphere::hooks
[x] Errors using miette
[ ] Combined Primary and Foreign Keys

Stable Release

[x] Postgres Composite Types
[x] Support Custom Types
[x] Runtime Inspection
[x] Provide Application Utils
[ ] Stabilize Traits
[ ] Stabilize Query Generation
[ ] Table Lenses (subsets / views)
[ ] validator support
[ ] Auto Timestamping

Advanced

[ ] Virtual Columns using (#[virtual = "<sql>"])
[ ] Soft Delete Support
[ ] Attribute Macro (#[query])
[ ] Custom queries

Longterm

[ ] Generate GraphQL + HTTP Servers?
[ ] Generate Graphs

Functionalities

Given a struct Model that derives its atmosphere schema using #[table]:

use atmosphere::prelude::*;

#[table(schema = "public", name = "model")]
struct Model {
    #[sql(pk)]
    id: i32,
    a: String,
    #[sql(unique)]
    b: String,
}

Atmosphere is able to derive and generate the following queries:

CRUD

`atmosphere::Create`

Model::create

`atmosphere::Read`

Model::read: read a Model by its primary key, returning a Model.
Model::find: find a Model by its primary key, returning an Option<Model>.
Model::read_all: read all Models, returning a Vec<Model>.
Model::reload

`atmosphere::Update`

Model::update
Model::upsert

`atmosphere::Delete`

Model::delete
Model::delete_by

Field Queries

Each struct field that is marked with #[sql(unique)] becomes queryable.

In the above example b was marked as unique so atmosphere implements:

Model::find_by_b: find a Model by its b field, returning an Option<Model>.
Model::delete_by_b: delete a Model by its b field.

Relationships & Inter-Table Queries

Given that a model contains fields are marked as a foreign key / point to another atmosphere::Table atmosphere – for example:

#[table(schema = "public", name = "submodel")]
struct Submodel {
    #[sql(pk)]
    id: i32,
    #[sql(fk -> Model)]
    super: i32,
}

Atmosphere is able to generate utility queries to move across Table boundaries:

Model::submodels
Model::delete_submodels
Submodel::model
Submodel::find_by_model
Submodel::delete_by_model

Note that the function names contain model and submodel – they are derived from the respective struct names.

Json support

Several databases support a JSON (and often JSONB) type, for which sqlx has native support through #[sqlx(json)] and #[sqlx(json(nullable))].

Since atmosphere only needs to know whether the column is JSON and to stay forward-compatible with future changes to sqlx's attribute, we use the following syntax:

#[table(schema = "public", name = "submodel")]
struct Submodel {
    #[sql(pk)]
    id: i32,
    #[sql(json)]
    #[sqlx(json)]
    data: HashMap<String, u64>,
    #[sql(json)]
    #[sqlx(json(nullable))]
    optional_data: Option<HashMap<String, String>>,
}

You can also manually handle the JSON support using the following (it will mean accessing the inner type through .as_ref() or .0):

use sqlx::types::Json;

#[table(schema = "public", name = "submodel")]
struct Submodel {
    #[sql(pk)]
    id: i32,
    data: Json<HashMap<String, u64>>,
    optional_data: Option<Json<HashMap<String, String>>>,
}

Contribution

We welcome contributions! Please see our contribution guidelines for more details.

License

Atmosphere is licensed under Apache 2.0.

Atmosphere

Install / Use

README