# ormkit
A comprehensive ORM layer for SQLx that provides type-safe database operations with minimal boilerplate.
## Features
- **Derive Macros**: Automatic implementation of Entity traits with `#[derive(ormkit::Entity)]`
- **ActiveModel Pattern**: Track field changes for efficient partial updates
- **Repository Pattern**: Generic CRUD operations for any entity
- **Query Builder**: Type-safe dynamic query construction with filters and ordering
- **Pagination**: Built-in offset and cursor-based pagination support
- **Transaction Management**: Automatic commit/rollback with transaction guards
- **Batch Operations**: Efficient bulk inserts, updates, and deletes
- **Relationship Loading**: Prevents N+1 queries with eager/lazy loading strategies
## Installation
```toml
[dependencies]
ormkit = "0.1"
ormkit-derive = "0.1"
sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres", "chrono", "uuid", "json"] }
```
## Quick Start
```rust
use ormkit::{Entity, Repository, QueryBuilder, Filter, Order, PaginationRequest};
use ormkit::active_value::ActiveValue;
use sqlx::PgPool;
use uuid::Uuid;
// Define an Entity using the derive macro
#[derive(ormkit::Entity, Debug, Clone)]
#[ormkit(table = "users")]
struct User {
#[ormkit(id)]
id: Uuid,
email: String,
name: String,
created_at: chrono::DateTime<chrono::Utc>,
}
// Repository operations (CRUD)
async fn repository_example(pool: &PgPool) -> Result<(), Box<dyn std::error::Error>> {
let repo = Repository::<User>::new(pool);
// Find by ID
let user = repo.find_by_id(user_id).await?;
// Find all
let all_users = repo.find_all().await?;
// Insert with ActiveModel
let mut user_model = UserActiveModel::default();
user_model.email = ActiveValue::Set("user@example.com".to_string());
user_model.name = ActiveValue::Set("John Doe".to_string());
let user = repo.insert(user_model).await?;
// Update (only changed fields are updated)
let mut user_model = user.into_active_model();
user_model.name = ActiveValue::Set("Jane Doe".to_string());
repo.update(user_model).await?;
// Delete
repo.delete(user_id).await?;
Ok(())
}
```
## Core Features
### Query Builder
```rust
use ormkit::{Filter, FilterOp, Order};
let users: Vec<User> = User::query()
.filter("email", FilterOp::Eq, "user@example.com")
.filter("created_at", FilterOp::Gt, chrono::Utc::now() - chrono::Duration::days(30))
.order_by("created_at", Order::Desc)
.limit(10)
.fetch_all(&pool)
.await?;
```
### Pagination
```rust
use ormkit::pagination::PaginationRequest;
let repo = Repository::<User>::new(&pool);
let request = PaginationRequest::new(1, 25); // page 1, 25 per page
let page = repo.paginate(&request).await?;
println!("Page {} of {}", page.meta.page, page.meta.total_pages);
for user in page.items {
println!("User: {}", user.email);
}
```
### Batch Operations
```rust
use ormkit::batch::{insert_many, BatchOptions};
let new_users = vec![/* ... */];
let options = BatchOptions::new().batch_size(50);
let result = insert_many(&pool, &new_users, Some(options)).await?;
println!("Inserted {} users", result.successful);
```
### Transactions
```rust
use ormkit::transaction::transaction;
let user = repo.find_by_id(user_id).await?;
let mut user_model = user.into_active_model();
user_model.name = ActiveValue::Set("Updated Name".to_string());
repo.update(user_model).await?;
Ok::<(), Box<dyn std::error::Error>>(())
}).await?;
```
## Advanced Features
### Relationships (Prevents N+1 Queries)
```rust
use ormkit::relations::RelationBuilder;
// Load related entities in a single query
let posts_with_users = RelationBuilder::for_entities(posts)
.load::<User>(&pool)
.await?;
for loaded in posts_with_users {
println!("Post: {} by {}", loaded.entity.title, loaded.related.name);
}
```
## Current Status
**v0.1.0** - Core features fully functional:
- ✅ Entity derive macros
- ✅ Repository CRUD operations
- ✅ Query builder with filters
- ✅ Pagination (offset and cursor-based)
- ✅ Transaction management
- ✅ Batch operations
- ⚠️ Relationship auto-loading (requires additional macro work)
For complex relationship loading, raw SQLx queries can still be used alongside ormkit.
## Documentation
Full API documentation is available at [docs.rs](https://docs.rs/ormkit).
## License
MIT OR Apache-2.0
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## See Also
- [SQLx](https://github.com/launchbadge/sqlx) - The underlying database driver
- [ormkit-derive](https://crates.io/crates/ormkit-derive) - Derive macros for ormkit