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_URLis wrong or the database is not running.table users already exists: the database already has auserstable from a previous prototype. Useruprizzle migrate reset --forcein development to drop and re-apply, or deletemigrations/and start fresh.no column named ...: the generated client is stale. Runruprizzle generate.