rorm to your dependencies
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:
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
Choose your async runtime
Currently, there are two runtimes supported.
Choose one of them and enable the respective crate feature to make
Add the chosen runtime to the features of
rorm, for example:
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.
rorm-mainfeature in your
[features]section, it will show them using checkboxes at the left edge.
rorm-mainshould not be set.
Annotate your main function:
rorm-mainfeature 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:
Make sure to have the CLI utility
Head over to project setup for more details, especially if you want to take some additional configuration for your setup.
Define a model
This simple example shows how to define a new database model in
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):
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 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
Make migration TOML files from the migrator JSON file
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
to compute the required database migrations as TOML files in the
migrations/. Note that those TOML files need to be applied
to the database as SQL statements by the
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
Database with a key
driver and some driver-specific options.
A simple example using a SQLite database looks like the following snippet:
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
--database-config to specify an alternative location
for the previously mentioned configuration file.