Expand description
An async ORM written in rust using sqlx and/or Tiberius.
§What is Welds
Welds is an ORM for the Rust programming language. The primary way to interact with Welds is by adding the “welds” macros to your structs. This adds to your structs Welds functions and allows for great autocompletion and very intuitive code.
§Macros - Setup your structs
To add welds to your struct you will need to derive welds::WeldsModel
#[derive(welds::WeldsModel)]
§Connect to table / view
Let welds know what DB table/schema it will be reading/writing data from
#[welds(schema = "public", table = "products")]
if you don’t want to allow writing to the table you can add readonly. (useful for views)
#[welds(readonly)]
§Build Relations for Joining
You can write queries that join across tables if you Wireup welds with relationships
Welds Supports:
- BelongsTo
- HasMany
They are both in the format:
[field, rust_path_to_other_object, "str_of_foreign_key_column"]
NOTE: Both BelongsTo
and HasMany
need to know the foreign_key column
If you are working on a struct that has a foreign_key to another table use a BelongsTo
#[welds(BelongsTo(product, super::product::product_id, "product_id"))]
struct Order {
product_id: ...,
...,
}
If you are working on a struct that has a foreign_key pointed at it, use a HasMany
#[welds(HasMany(orders, super::order::Order, "product_id"))]
struct Product {
...,
}
If working with a many-to-many relationship, add a HasMany
on both structs, and add two BelongsTo
on the join table struct
#[welds(BelongsTo(order, super::order::Order, "order_id"))]
#[welds(BelongsTo(product, super::product::Product, "product_id"))]
struct ProductOrders {
#[welds(primary_key)]
id: i32,
order_id: i32,
product_id: i32,
}
§Fields Level Attributes
There are a couple attributes you can add to your fields to help control how welds functions
#[welds(primary_key)]
Important! Add this to the primary key of your table.#[welds(rename = "xyz")]
let welds know the underlying column has a different name than the field#[welds(ignore)]
Tell welds this fields it not in the database.
§Putting it all together
Here is a working example of what a fully setup struct might look like
#[derive(Debug, welds::WeldsModel)]
#[welds(schema = "public", table = "products")]
#[welds(HasMany(order, super::order::Order, "product_id"))]
pub struct Product {
#[welds(primary_key)]
#[welds(rename = "product_id")]
pub id: i32,
pub active: Option<bool>,
pub description: Option<String>,
pub name: String,
}
§Using Welds
When WeldsModel is added to your struct the following is added directly to your model
Model::new()
make a new model ready to be saved to the databaseModel::find_by_id()
Model::all()
start a query for a ModelModel::where_col()
start a query for a ModelModel::from_raw_sql()
finds Model using raw custom SQL str
Instances of your model are wrapped in a welds::state::DbState. From your instance you can update, create, and delete.
Start a query from the struct that derived WeldsModel
let client = welds::connections::postgres::connect(&url).await.unwrap();
let sellers = Product::all()
.where_col(|product| product.price.equal(3.50))
.map_query(|product| product.seller )
.where_col(|seller| seller.name.ilike("%Nessie%") )
.order_by_desc(|seller| seller.id )
.limit( 10 )
.run(&client).await?;
For more examples on how to use Welds check out the Example Repo
§Examples:
- Basic CRUD
- Mapping Queries / Joining
- Bulk (Create/Update/Delete)
- Select Only Specific Columns
- Checking DB schema matches compiled structs
§Features
- postgres - enables postgres database connection. (requires sqlx setup)
- mysql - enables MySql database connection. (requires sqlx setup)
- sqlite - enables Sqlite database connection. (requires sqlx setup)
- mssql - enables Microsoft SQL support. (requires tokio runtime.)
- detect - enables scanning of the database to get schema info
- check - enables checking your models against table in the database
- migrations - adds all the migration structs and traits
- full - all the features excluding (mock)
- mock - Use for testing ONLY. Enables mocking out database schemas
§Important Notes:
- If you are using one of the
sqlx
connections, you will need to setup sqlx. This is so you can pick an async runtime.
Re-exports§
pub use errors::WeldsError;
pub use welds_connections as connections;
Modules§
Structs§
- Re-export welds_connections A row of data from the database
Enums§
- Re-export welds_connections
Traits§
- Re-export welds_connections The common trait for database connections and transactions.
- Re-export welds_connections Implementers of this trait can crate a transaction. If you want to create a transaction off of a Client, make sure you
use welds::TransactStart
Derive Macros§
- Re-export the Macro used to make models