Getting Started

Add `rorm` to your dependencies

[dependencies]
rorm = { version = "*" }

If you want to use a development version, clone the repository and specify the path explicitly or use the git URL directly. This uses the latest commit on the default branch if not specified otherwise, for example:

[dependencies]
rorm = { git = "https://github.com/rorm-orm/rorm", branch = "dev" }

Danger

Be aware that this documentation is written for the current released version.

To use the dev branch you want to use the docs generated by executing cargo doc.

Choose your async runtime

Currently, there are two runtimes supported. Choose one of them and enable the respective crate feature to make rorm work:

tokio
async-std

Add the chosen runtime to the features of rorm, for example:

[dependencies]
rorm = { version = "*", features = ["tokio"] }

Setup `rorm-main`

This step is strictly speaking optional, but it's highly recommended. rorm-main is a feature to ease the integration with the migrator, therefore it's unnecessary if the migrator isn't used. It overwrites the main function when activated, which will produce a JSON file of the currently known models in the source code. The recommended procedure is to use this feature in a build pipeline, for extended testing purposes or whenever you want to make new migrations of the models.

Add the rorm-main feature in your Cargo.toml:
```
[features]
rorm-main = []
```
Make sure to disable this feature by default. For example, IntelliJ manages which features will be enabled internally. When looking at the [features] section, it will show them using checkboxes at the left edge. rorm-main should not be set.
Annotate your main function:
```
#[rorm::rorm_main]
fn main() {
    // ...
}
```
This attribute won't do anything unless the rorm-main feature becomes enabled. Depending on the chosen runtime implementation, you may need another annotation for that. For example, for Tokio you would combine the annotations in one piece as follows:
```
#[rorm::rorm_main]
#[tokio::main]
async fn main() {
    // ...
}
```

Project setup

Make sure to have the CLI utility rorm-cli available:

cargo install -f rorm-cli

Head over to project setup for more details, especially if you want to take some additional configuration for your setup.

Define a model

use rorm::prelude::*;

#[derive(Model)]
pub struct User {
    #[rorm(id)]
    pub(crate) id: i64,

    #[rorm(max_length = 255)]
    pub(crate) username: String,

    pub(crate) age: i16
}

This simple example shows how to define a new database model in rorm. Just derive from Model and annotate the attributes of the struct with additional information. Some fields, for example strings, have mandatory annotations (in this case, max_length). See model declaration for further details.

Since Rust structs don't provide default values, you can use special "patch structs" that allow you to omit all but the specified values. Those patch structs come in handy to omit auto-generated or default values (e.g., the ID):

use rorm::Patch;

#[derive(Clone, Debug, Patch)]
#[rorm(model = "User")]
pub(crate) struct UserNew {
    pub(crate) username: String,
    pub(crate) age: i16,
}

Example

There's a full example to demonstrate using the model as well as patches.

Set up a database and migrations

Generate migrator files

After the first database model has been added, the current models can be extracted from the Rust source code:

cargo run --features rorm-main

This will create a file .models.json to be processed by the migrator. So, you need to run this every time you want to generate new migrations. You might want to add it to a build chain if you're using any. It requires the rorm-main feature to be set up properly (see above).

Make migration TOML files from the migrator JSON file

rorm-cli make-migrations

Otherwise, if you configured the commands as outlined here, it's also possible to invoke those rorm-cli commands via cargo make <cmd>.

This command will read the previously generated JSON file .models.json to compute the required database migrations as TOML files in the directory migrations/. Note that those TOML files need to be applied to the database as SQL statements by the subcommand rorm-cli migrate later. Head over to the docs for those migration files for details about the file format.

Configure the database connection

At some point in the application, rorm needs to know where to connect to a database to actually do operations on it. This also applies to the migrator utilities. The latter depends on a TOML configuration file to read those settings. Therefore, it's probably most straightforward to use a TOML file for your application configuration as well. The basic TOML file contains a section Database with a key driver and some driver-specific options. A simple example using a SQLite database looks like the following snippet:

[Database]
# Valid driver types are: "MySQL", "Postgres" and "SQLite"
Driver = "SQLite"

# Filename of the database
Filename = "sqlite.db"

Of course, you can add other sections and keys to that config file to make it suitable for your application.

Migrate the initial migrations

rorm-cli migrate

This command will finally write the TOML-based migration files to the database. The model has been transformed into a database table users.

Use --database-config to specify an alternative location for the previously mentioned configuration file.