# Premix ORM
Premix ORM is a zero-overhead, type-safe ORM for Rust, designed for performance and developer experience.
This crate (`premix-orm`) is the official facade that re-exports `premix-core` and `premix-macros`, providing a unified entry point for your application.
## Research Status
This crate is part of an AI-assisted research prototype. APIs may change and production use is not recommended yet.
## Requirements
- Rust 1.85+ (edition 2024).
- No nightly toolchain required.
## Why use this facade?
- Unified imports: `use premix_orm::prelude::*;` gets you everything.
- No version mismatch: core and macros versions stay compatible.
- Clean dependencies: only one crate to add to your `Cargo.toml`.
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
premix-orm = "1.0.9-alpha"
sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
```
## Database Features
Enable database features on both `premix-orm` and `sqlx`:
```toml
premix-orm = { version = "1.0.9-alpha", features = ["postgres", "axum"] }
sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite", "postgres"] }
```
## Feature Flags
| `sqlite` | Enable SQLite support (default) |
| `postgres` | Enable PostgreSQL support |
| `mysql` | Enable MySQL support |
| `axum` | Enable Axum integration (`PremixState`) |
| `actix` | Enable Actix-web integration (`PremixData`) |
| `metrics` | Enable Prometheus metrics (`install_prometheus_recorder`) |
## Quick Start
```rust
use premix_orm::prelude::*;
use serde::{Deserialize, Serialize};
#[derive(Model, Debug, Serialize, Deserialize)]
pub struct User {
pub id: i32,
pub name: String,
// Soft delete is auto-detected by field name.
pub deleted_at: Option<String>,
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let pool = Premix::smart_sqlite_pool("sqlite::memory:").await?;
// Sync schema.
Premix::sync::<premix_orm::sqlx::Sqlite, User>(&pool).await?;
// CRUD.
let mut user = User { id: 0, name: "Alice".to_string(), deleted_at: None };
user.save(&pool).await?;
user.name = "Alice Updated".to_string();
user.save(&pool).await?; // Updates when id is set.
println!("Saved user with ID: {}", user.id);
Ok(())
}
```
## Common Query Helpers
```rust
// Fetch all rows.
let users = User::all(&pool).await?;
// Find by primary key.
let user = User::find_by_id(&pool, 1).await?;
// Bulk update by primary key.
let updated = User::update_by_id(&pool, 1, serde_json::json!({ "name": "New" })).await?;
```
## Features
- Compile-time SQL generation via macros
- Application-level eager loading using batched queries
- Optional soft delete support by `deleted_at` convention
- SQLite, Postgres, and MySQL via `sqlx` feature flags
- Axum and Actix-web integrations via feature flags
- Prometheus metrics collection support
## Error Mapping Helpers
If you want domain errors instead of raw `sqlx::Error`, use `ModelResultExt`:
```rust
use premix_orm::prelude::*;
# async fn example(pool: premix_orm::sqlx::SqlitePool) -> PremixResult<()> {
let mut user = User { id: 1, name: "Alice".to_string() };
user.save_result(&pool).await?;
Ok(())
# }
```
## Axum Integration
Use `PremixState` as your Axum state wrapper:
```rust
use axum::{routing::get, Router};
use premix_orm::{prelude::*, PremixState};
async fn health() -> &'static str {
"ok"
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let pool = Premix::smart_sqlite_pool("sqlite::memory:").await?;
Premix::sync::<premix_orm::sqlx::Sqlite, User>(&pool).await?;
let app = Router::new()
.route("/health", get(health))
.with_state(PremixState::new(pool));
Ok(())
}
```
## Compatibility
- Requires `sqlx` with matching database features
- Works with the Tokio runtime
## Book
For a longer-form guide, see `orm-book/` in this repository.
## SQL Transparency
Inspect the SQL generated by the query builder:
```rust
let query = User::find_in_pool(&pool).filter_gt("age", 18).limit(10);
println!("{}", query.to_sql());
```
See the book for more on generated APIs and SQL inspection: `orm-book/src/queries.md`.
## Raw SQL Escape Hatch
Run raw SQL while mapping results to your model:
```rust
let users = User::raw_sql("SELECT * FROM users WHERE active = 1")
.fetch_all(&pool)
.await?;
```
## License
This project is licensed under the MIT license.