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

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

Beta Release

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

Stable Release

• Postgres Composite Types
• Support Custom Types
• Runtime Inspection
• 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.