Welds ORM

Use welds::connections::connect(url) to establish an asynchronous connection to your database. The connection URL format depends on your database driver (e.g., postgres://...).

let url = "postgres://postgres:password@localhost:5432";
let client = welds::connections::connect(url).await.unwrap();

You can install the welds-cli tool using cargo. Note that this tool is deprecated in favor of Gumbo.

cargo install welds-cli

To generate Rust struct definitions for your database tables using welds-cli, follow these steps:

1. Set the DATABASE_URL environment variable to your database connection string.
2. Run welds update to create a welds.yaml database definition file.
3. Run welds generate to produce the Rust files for your tables.

# 1. Set connection string
export DATABASE_URL=postgres://postgres:password@localhost:5432

# 2. Create welds.yaml definition
welds update

# 3. Generate rust code
welds generate

To use the SQLite example, you must set the DATABASE_URL environment variable to point to a local SQLite file. The format follows the sqlite:// protocol followed by the absolute path to the database file.

export DATABASE_URL="sqlite://$PWD/test.sqlite"

Welds allows using types from external crates like chrono or serde_json, but you must enable the corresponding features in the underlying drivers (sqlx or Tiberius).

For SQLX (Postgres, MySQL, Sqlite):

1. Add the external crate: cargo add chrono
2. Enable the feature in sqlx: cargo add sqlx --features=chrono

For Tiberius (MSSQL):

1. Add the external crate: cargo add chrono
2. Enable the feature in welds-connections: cargo add welds-connections --features=mssql,mssql-chrono

Available welds-connections features for MSSQL:

• mssql-chrono
• mssql-time
• mssql-rust_decimal
• mssql-bigdecimal

Relationships between models are defined using the #[welds(...)] attribute on the struct. Supported relationship types include:

• HasMany
• BelongsTo
• HasOne
• ManualRelationship
• JoinTable (for many-to-many relationships)

#[welds(HasMany(posts), BelongsTo(user))]
struct Post {
    // ...
}

The AnyClient enum acts as a unified wrapper around various database connections. It allows you to write code that works across different database backends (like Postgres, MySQL, SQLite, or MSSQL) by implementing the Client trait. The specific available backends depend on the cargo features enabled in your project.

Available variants (based on enabled features):

• Sqlite(crate::sqlite::SqliteClient)
• SqliteSync(crate::sqlite_sync::SqliteClient)
• Postgres(crate::postgres::PostgresClient)
• Mysql(crate::mysql::MysqlClient)
• Mssql(crate::mssql::MssqlClient)
• Noop(crate::noop::NoopClient)

The QueryBuilder<T> is a fluent API used to build un-executed SQL queries that can be run against a database. It can be chained to add filters, ordering, limits, and joins. You typically start a query using a model's static methods (e.g., Thing::all()).

use welds::prelude::*;

// Starting a query for the 'Thing' model
let query = Thing::all()
    .where_col(|c| c.id.gt(10))
    .limit(5)
    .order_by_asc(|c| c.id);

// Executing the query
let rows = query.run(db).await?;

When you define relations on a model, Welds automatically implements the HasRelations trait for your struct. This implementation enables lambda-based selection of relationships.

It generates a companion struct (the name of which is provided in your configuration) that contains fields for each relationship. These fields use specific relationship types from the welds::relations module, such as BelongsTo<Model, OtherModel>, HasMany<Model, OtherModel>, or HasOne<Model, OtherModel>.