44 releases (8 breaking)
new 0.9.1 | Jan 20, 2025 |
---|---|
0.8.4 | Jan 9, 2025 |
0.8.3 | Dec 20, 2024 |
0.7.2 | Nov 26, 2024 |
0.5.2 | Jul 19, 2024 |
#471 in Database interfaces
564 downloads per month
Used in 4 crates
305KB
5K
SLoC
Overview
GeekORM is a simple Object Relation Mapper for empowering your Rust development.
✨ Features
- Focus on simplicity
- Rely on Derive Macros to generate code for your structs
- Using
Table
- Using
Data
- Using
- Dynamically generate functions and corresponding SQL queries
.save(...)
- Inserting new rows.update(...)
- Updating existing rows.delete(...)
- Deleting rows
- Support for Backends Drivers
- Automatic Migration Generation
geekorm-cli init
- Setup your migrations
- Extensive crate features
rand
: Generate random strings (set lenght, set prefix, set enviroment)hash
orpassword
: Generate secure Hashes of passwords (set algorithm)- and more...
- Documentation
📦 Installation
🦀 Library
You can install the library from crates.io:
cargo add geekorm
Add the backend driver you want to use
cargo add rusqlite
# OR
cargo add libsql
Along with the backend driver for geekorm
:
cargo add geekorm -F rusqlite
# OR
cargo add geekorm -F libsql
🛠️ CLI
If you want to manage your models and migrations using geekorm
, you'll need to install the geekorm-cli
command line tool.
cargo install geekorm-cli
🏃 Getting Started
GeekORM is easy to setup and use in your Rust project.
🏎️ Setting Up Migrations
The first thing you'll need to decide is if you want to use the geekorm-cli
to manage your migrations or if you want to manage them manually.
You can use the geekorm-cli
to help you manage your migrations.
geekorm-cli init
This will prompt you to enter some information about your setup and will generate a crate
or a module
for you to use.
Once you have setup your project, 2 new commands will be available to you:
# Generate a new migration (creates a new folders in your migrations directory)
geekorm-cli migrate
# Validate your migrations (runs from your initial migration to the latest)
geekorm-cli test
🚀 Writing your first model
Once you have installed geekorm
, you can start using the derive macros like the following:
use anyhow::Result;
use geekorm::prelude::*;
/// Using the `Table` derive macro to generate the `Users` table
#[derive(Table, Debug, Default, serde::Serialize, serde::Deserialize)]
struct Users {
#[geekorm(primary_key, auto_increment)]
id: PrimaryKeyInteger,
/// Unique username field
#[geekorm(unique)]
username: String,
/// Password field with automatic hashing
#[geekorm(hash)]
password: String,
/// User Type Enum (defaults to `User`)
#[geekorm(new = "UserType::User")]
user_type: UserType,
}
#[derive(Data, Debug, Default, Clone)]
enum UserType {
Admin,
Moderator,
#[default]
User,
}
#[tokio::main]
async fn main() -> Result<()> {
// Setup the database and connection
let conn = rusqlite::Connection::open_in_memory().expect("Failed to open database");
// Initialize or migrate the database using the `crate` or `module`.
// This is done using the `geekorm-cli` function
db::init(&conn).await?;
// [OR] You can create the tables manually
Users::create_table(&conn).await?;
// Use the generated `new` function to create a new User
// using the default values set in the struct.
let mut user = Users::new("GeekMasher", "ThisIsNotMyPassword");
// Saving the new User in the database
user.save(&connection).await?;
// Print the Primary Key value set by the database (auto_increment)
println!("User ID: {:?}", user.id);
// Updating the Users account type to Admin
user.user_type = UserType::Admin;
user.update(&connection).await?;
// Fetch the Admin Users
let admin_users = Users::fetch_by_user_type(&connection, UserType::Admin).await?;
println!("Admin Users: {:?}", admin_users);
// Counts the number of Users in the database
let total_users = Users::total(&connection).await?;
println!("Total Users: {:?}", total_users);
Ok(())
}
🏄 Create Features
There are a number of opt-in features supported by GeekORM.
Features can be added either using cargo add geekorm -F all
or added them directly in your Cargo.toml
file.
all
: Enable all the major stable featuresnew
: GenerateTable::new(...)
functionshelpers
: Generate a number of helper functions- Select
Table::select_by_primary_key()
- Select column
Table::select_by_{field}()
- Select
rand
: Support Generating random stringshash
: Support Generating password hashes- Backends
libsql
: Add LibSQL backend supportrusqlite
: Add Rusqlite backend support
🧑🤝🧑 Maintainers / Contributors
Mathew Payne 💻 👀 |
Cale 🎨 |
🦸 Support
Please create GitHub Issues if there are bugs or feature requests.
This project uses Semantic Versioning (v2) and with major releases, breaking changes will occur.
📓 License
This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.
Dependencies
~2–13MB
~165K SLoC