Getting Started
Dependencies
tokio
Rorm uses async rust and the only supported runtime is tokio.
If you never heard of it, you probably should look up some quick introduction to async.
rorm
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:
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.
CLI tool
Make sure to have the CLI utility rorm-cli available:
Head over to project setup for more details, especially if you want to take some additional configuration for your setup.
Alternatively you can enable rorm's cli feature which re-exports the binaries functions.
This allows you to integrate the migrate command into your binary's cli.
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.
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 could run this snippet through some kind of subcommand in your binary's development builds.
Make migration TOML files from the migrator JSON file
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
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.