Crate tiny_orm

use sqlx::{FromRow, Row, types::chrono::{DateTime, Utc}};
use tiny_orm::Table;

#[derive(Debug, FromRow, Table, Clone)]
#[tiny_orm(all)]
struct Todo {
    id: i32,
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    description: String,
    done: bool,
}

The code above would generate the following methods on the Todo object

impl Todo {
    pub fn get_by_id(pool: &DbPool, id: &i32) -> sqlx::Result<Self> {
        // Get a specific record for a given ID
        // Use the `id` column by default
    }
    pub fn list_all(pool: &DbPool) -> sqlx::Result<Vec<Self>> {
        // Get all the records
    }
    pub fn delete(&self, pool: &DbPool) -> sqlx::Result<()> {
        // Delete the record in the database
    }
    pub fn create(&self, pool: &DbPool) -> sqlx::Result<i32> {
        // Create the Todo object as a record in
        // the database and returns the primary key of the record created.
    }
    pub fn update(&self, pool: &DbPool) -> sqlx::Result<()> {
        // Update the record in the database with the values
        // currently part of the Todo object
    }
}

Examples

More examples can be found in the examples directory.

Options

The Table macro comes with a few options to give flexibility to the user

At the Struct level

• table_name: The name of the table in the database. Default being a snake_case version of the Struct name. So MyStruct would have my_struct as a default table_name.
• only: The methods that will only be available to that struct. Multiple values are comma separated. Default is dependent on the struct name (see below).
• exclude: The methods that will be excluded for that struct. Multiple values are comma separated Default empty vec.
• add: The methods that will be added for that struct. Multiple values are comma separated Default empty vec.
• all: All the methods will be available to the struct. This will override the default values when none are provided. Default none.
• soft_deletion: When set to true, it will add a deleted_at filter when querying the data. When using the delete method, it will set the deleted_at column to the current timestamp. Default false.
• return_object: A custom object that would be returned instead of Self. Useful when creating or updating records with partial information. Default is Self which corresponds to the current Strut.

Note: only cannot be used with exclude nor add cannot be used together.

By convention, if a struct name

• Starts with New then it will automatically use the following arguments #[tiny_orm(table_name = "table_name_from_return_object", return_object = "NameWithoutNewAsPrefix", only = "create")]
• Starts with Update then it will automatically use the following arguments #[tiny_orm(table_name = "table_name_from_return_object", return_object = "NameWithoutUpdateAsPrefix", only = "update")]
• Everything else would be the equivalent of using the following #[tiny_orm(table_name = "table_name", return_object = "Self", exclude = "create,update")]

Example using the default options

#[derive(Debug, FromRow, Table, Clone)]
// #[tiny_orm(table_name = "todo", return_object = "Self", exclude = "create,update")]
struct Todo {
    id: i32,
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    description: String,
    done: bool,
}

#[derive(Debug, FromRow, Table, Clone)]
// Because the struct name starts with "New", it would automatically use the following options
// #[tiny_orm(table_name = "todo", return_object = "Todo", only = "create")]
struct NewTodo {
    description: String,
}

#[derive(Debug, FromRow, Table, Clone)]
// Because the struct name starts with "Update", it would automatically use the following options
// #[tiny_orm(table_name = "todo", return_object = "Todo", only = "update")]
struct UpdateTodo {
    id: i32,
    done: bool
}

The above takes the assumption that some columns can be nullable and others are auto generated (eg an ID column that would be auto increment). Thus it would generate the following

impl NewTodo {
    pub fn create(&self, pool: &DbPool) -> sqlx::Result<Todo> {
        // Use the NewTodo object to create a record
        // in the database and return the record created.

        // This would not be supported for MySQL since
        // there is a need to know the primary key (auto increment or not)
        // to either return the value or use `last_insert_id()`
    }
}

impl UpdateTodo {
    pub fn update(&self, pool: &DbPool) -> sqlx::Result<Todo> {
        // Update the Todo object with partial information based
        // on the id (default primary_key).
        // Because `return_type` is specified, it will return the whole record in the database.
        // If `return_type` was not specified, it would simply return nothing `()`.

        // For MySQL, it would always return nothing `()` as it
        // cannot return a record after an update.
    }
}

Example using the soft_deletion option

#[derive(Debug, FromRow, Table, Clone)]
#[tiny_orm(soft_deletion)]
struct Todo {
    id: i32,
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    deleted_at: DateTime<Utc>,
    description: String,
    done: bool,
}

#[derive(Debug, FromRow, Table, Clone)]
#[tiny_orm(soft_deletion)]
struct UpdateTodo {
    id: i32,
    done: bool
}

At the field level

• primary_key: The field that would be used as a primary key for the queries. For some methods the primary key is mandatory (eg: get_by_id()). If not specified, it will default to id if part of the struct.
• primary_key(auto): The field that would be used as a primary key for the queries. When “auto” is set, it will skip the column and returns it during the create() method since it will be auto generated by the database itself.

Note: MySQL only supports “auto increment” in that case. It does not support returning the default value of a primary key like a UUID.

Example

#[derive(Debug, FromRow, Table, Clone)]
struct Todo {
    #[tiny_orm(primary_key)]
    custom_pk: Uuid,
    description: String,
    done: bool
}

use tiny_orm::{Table, SetOption};
#[derive(Debug, FromRow, Table, Clone)]
struct Todo {
    #[tiny_orm(primary_key(auto))]
    id: i64,
    description: SetOption<String>,
    done: SetOption<bool>
}

Thus it would generate the following

impl Todo {
    pub fn create(&self, pool: &DbPool) -> sqlx::Result<Uuid> { // or i64 depending on the example
        // Create the Todo object as a record in
        // the database and returns the created record.
    }
}

Enums

SetOption

tiny_orm::SetOption is an enum that behave similarly to Option in the sense that there are only two variants. The goal is to easily differentiate between an Option type and a SetOption type. So that it is possible to have a struct like the following

TinyOrmError

Derive Macros

Table