Skip to content

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

The recommended setup commits to PostgreSQL as the only database backend:

[dependencies]
rorm = { version = "0.10", default-features = false, features = [
    "postgres-only",
    # pick the integrations you need:
    "time",
    "uuid",
] }

If you need SQLite (or want to keep the choice open), use the default features instead, which enable both backends:

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

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.

Cargo features

The most relevant feature flags:

  • postgres-only (recommended): enables only the PostgreSQL backend. Committing to postgres unlocks some postgres-specific functionality, e.g. additional field types (IpNetwork, MacAddress, BitVec), case-insensitive comparisons (ilike) and row locking.
  • all-drivers (default): enables both the PostgreSQL and the SQLite backend while restricting you to functionality supported by both.
  • chrono, time (default): field types from the respective datetime crate.
  • uuid, url (default): field types from the respective crate.
  • cli: re-exports rorm-cli, allowing you to embed e.g. the migrate command into your own binary.

Since postgres-only and all-drivers are mutually exclusive and the latter is part of the default features, using postgres-only requires default-features = false (re-add the datetime and other integrations you need).

CLI tool

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.

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.

rorm::write_models(File::create(".models.json")?)?

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

rorm-cli make-migrations

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.

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

# Name of the database
Name = "my-application"
# Host and port the database is listening on
Host = "127.0.0.1"
Port = 5432
# Credentials to connect with
User = "my-application"
Password = "super-secure"

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

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

Note

Support for MySQL / MariaDB has been removed in rorm v0.10.0. The supported databases are PostgreSQL and SQLite.

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.