Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quickstart

From an empty directory to a working query in under five minutes.

Prerequisites

  • Rust 1.85 or later.
  • A running PostgreSQL, MySQL/MariaDB, or SQLite 3 database. SQLite needs no server; just a writable file path.

This guide uses PostgreSQL. To use SQLite, replace --provider postgres with --provider sqlite and set DATABASE_URL to a file path such as sqlite://./dev.db.

1. Install the CLI

1.5.1 is the current release on crates.io, so a bare cargo install resolves to the latest stable:

cargo install ruprizzle-cli

2. Scaffold a project

mkdir my-app && cd my-app
ruprizzle init --provider postgres

This creates:

my-app/
  schema.ruprizzle
  .env
  .gitignore
  migrations/
    README.md
  src/
    main.rs

Open .env and update DATABASE_URL:

DATABASE_URL="postgres://user:password@localhost:5432/my_app_db?sslmode=disable"

3. Edit the schema

Replace schema.ruprizzle with:

datasource db {
  provider = "postgres"
  url      = env("DATABASE_URL")
}

generator client {
  output      = "src/db"
  module_name = "db"
}

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String
}

4. Create and run the first migration

ruprizzle migrate dev --name init

This diffs the empty database against the schema, writes a migration under migrations/, applies it, and regenerates the client.

5. Add dependencies

cargo add ruprizzle
cargo add tokio --features tokio/full
cargo add dotenvy
cargo add sqlx@0.8.6 --no-default-features --features "runtime-tokio-rustls,postgres"
cargo add serde

Or edit Cargo.toml:

[dependencies]
ruprizzle = "1.5"
tokio = { version = "1", features = ["full"] }
dotenvy = "0.15"
sqlx = { version = "0.8.6", default-features = false, features = ["runtime-tokio-rustls", "postgres"] }
serde = "1.0.229"

6. Write the first query

Make src/main.rs:

mod db;

#[tokio::main]
async fn main() -> Result<(), ruprizzle::Error> {
    dotenvy::dotenv().ok();
    let db_url =
        std::env::var("DATABASE_URL").map_err(|e| ruprizzle::Error::Message(e.to_string()))?;
    let db = db::Db::connect(&db_url).await?;

    let alice = db
        .user()
        .create(db::UserInsert {
            id: None,
            email: "alice@example.com".into(),
            name: "Alice".into(),
        })
        .exec()
        .await?;

    let users = db
        .user()
        .find_many()
        .filter(db::user::EMAIL.ends_with("@example.com"))
        .order_by(db::user::NAME.asc())
        .fetch_all()
        .await?;

    println!("created: {:?}", alice);
    println!("users: {:?}", users);
    Ok(())
}

Run it:

cargo run

7. Iterate

Change schema.ruprizzle and run:

ruprizzle migrate dev --name add_field

migrate dev already regenerates the client. For live code generation while you edit the schema without migrating, use:

ruprizzle generate --watch

Common first errors

  • Failed to acquire connection: DATABASE_URL is wrong or the database is not running.
  • table users already exists: the database already has a users table from a previous prototype. Use ruprizzle migrate reset --force in development to drop and re-apply, or delete migrations/ and start fresh.
  • no column named ...: the generated client is stale. Run ruprizzle generate.

Next steps