Getting started

Rent is a Rust-native relational database toolkit. You define the application data model in a central Rent Schema Language (RSL) document, generate an async typed Rust client, and manage the matching database through explicit, reviewable migrations.

Rent supports PostgreSQL, MySQL, MariaDB, and SQLite. The generated client provides typed CRUD, relationships and eager loading, transactions, optimistic locking, pagination, streaming, policies, and observability without requiring a hosted service.

What you will build

This guide creates a private SQLite application with:

• a central RSL schema;
• a generated, statically typed client;
• a checksummed database migration;
• a real local database; and
• an async application connected through Tokio.

SQLite keeps the first run self-contained. The same schema and client workflow applies to PostgreSQL, MySQL, and MariaDB.

Before you begin

Rent is currently installed from a checked-out workspace. On macOS or Linux, install Rust through rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

source "$HOME/.cargo/env"

On Windows, download and run rustup-init.exe, then open a new terminal.

Verify the installation from the Rent repository root:

rustup --version
rustc --version
cargo --version

The workspace's rust-toolchain.toml automatically installs and selects Rent's supported Rust compiler, Clippy, and rustfmt when you run a Rust command from this directory.

Install nextest before running the test commands used later in the guide:

cargo install --locked cargo-nextest

cargo nextest --version

Install the command-line application from the Rent repository root:

cargo install --locked --path crates/rent-cli

rent --version

The Install Rent page also covers existing Cargo applications, backend features, and updating a local checkout.

Create an application

Create a new SQLite application beside the Rent checkout:

cd ..
rent new social-app --database sqlite
cd social-app

rent new creates Cargo configuration, a starter User entity, generated client code, migration directories, formatter settings, a local .env containing DATABASE_URL, and a path dependency back to the Rent workspace. Rent loads that project .env automatically.

Check the complete project before changing the database:

rent doctor

Rent Doctor

Ready Configuration  ./rent.toml
Ready Cargo project
Ready Schema         1 entity
Ready Client         generated and current
Ready Migrations     no migration history yet
Ready Database       sqlite connection verified

Healthy: Rent project is healthy.

Create the database schema

Turn the starter RSL model into the first migration and apply it:

rent migrate dev --name initial

migrate dev performs a complete local feedback loop. It inspects the database, plans the difference, writes a checksummed SQL migration, applies pending migrations, and inspects again to prove the database now matches the RSL schema.

Migration: initial

Created ./rent/migrations/20260910023750_initial.sql (1 change)
Applied 20260910023750_initial (1 statement)
Verified: Database matches the RSL schema.

Compile and run the generated application:

cargo check
cargo run

Rent connected

At this point the complete path works: RSL schema → generated Rust client → reviewed migration → live database → async application.

Understand the generated project

The files you will work with most often are:

Code generation and migration planning both read the same rent/schema.rsl source of truth.

Make your first schema change

Open rent/schema.rsl and expand the starter model:

model User {
  id      BigInt @id @default(autoincrement())
  email   String @unique
  name    String
  version UInt   @rent.version

  @@map("users")
}

Inspect Rent's interpretation, rebuild the client, and migrate the development database:

rent describe
rent generate
rent migrate preflight
rent migrate dev --name add_user_profile

Use rent dev in another terminal when you want generation to follow schema edits automatically.

Use the typed client

The generated client accepts borrowed strings and exposes methods derived from the schema:

let ada = client
    .create_user()
    .email("ada@example.com")
    .name("Ada")
    .save()
    .await?;

let same_user = client
    .user()
    .email_eq("ada@example.com")
    .only()
    .await?;

only() returns one row or a typed cardinality error. Use only_or_none(), all(), count(), projections, pages, or bounded streams when the expected result shape differs.

The generated application connects from DATABASE_URL:

let database_url = std::env::var("DATABASE_URL")?;

let client = generated::client::Client::connect(&database_url).await?;

Use Client::connect_with when the application needs custom pool limits, acquisition timeouts, or connection lifetime settings.

Browse the result

Open the development database in Rent Studio:

rent studio

Studio opens a loopback-only web interface and is read-only by default. Press Ctrl+C in its terminal to stop it.

Your everyday loop

Once the project is established, most schema work follows this sequence:

rent describe
rent generate
rent migrate preflight
rent migrate dev --name describe_the_change
cargo nextest run

Use rent doctor whenever configuration, generated code, migrations, Cargo features, or database connectivity seem inconsistent.

Choose what to learn next

When the application is headed toward a real environment, finish with production deployment and application testing.