Crate rust_query 

Example

#[schema(MySchema)]
pub mod vN {
    // Structs are database tables.
    pub struct User {
        pub name: String,
    }
    pub struct Image {
        // This column has a unique constraint.
        #[unique]
        pub file_name: String,
        // This column has an index and a foreign key constraint to the `User` table.
        #[index]
        pub uploaded_by: User,
    }
}
// Import the table names from the schema we just created.
use v0::*;

fn main() {
    let database = Database::new(Config::open("my_database.sqlite"));

    database.transaction_mut_ok(|txn| {
        // First we insert a new `User` in the database.
        // There are no unique constraints on this table, so no errors to handle.
        let mike = txn.insert_ok(User { name: "mike" });
        // Inserting an `Image` can fail, because of the unique constraint on
        // the `file_name` column.
        txn.insert(Image {
            file_name: "dog.png",
            uploaded_by: mike,
        })
        .expect("no other file called `dog.png` should exist");
    }); // Changes are committed at the end of the closure!

    database.transaction_mut_ok(|txn| {
        let ref dog = txn.lazy(Image.file_name("dog.png")).expect("`dog.png` should exist");
        // Note that this automatically retrieves the `User` row that matches the image!
        println!("`dog` image was uploaded by {}", dog.uploaded_by.name);
        
        let ref user = dog.uploaded_by;
        let upload_count = txn.query_one(aggregate(|rows| {
            let user_images = rows.join(Image.uploaded_by(user));
            // No error handling is required for this aggregate, an integer is always returned.
            // This works even if `rows` is empty.
            rows.count_distinct(user_images)
        }));
        println!("{} uploaded {} images", user.name, upload_count);
        
        // Since we are going to do mutations now, we need to disable
        // the automatic retrieval of column data for the rows that
        // we still want to use.
        let dog = dog.table_row();
        let user = user.table_row();

        let paul = txn.insert_ok(User { name: "paul" });
        // We can mutate rows with a simple assignment.
        txn.mutable(dog).uploaded_by = paul;
    
        // Deleting happens in a separate transaction mode.
        let txn = txn.downgrade();
        // Since users can be referenced by images, we need to handle a potential error.
        txn.delete(user).expect("no images should refer to this user anymore");
    });
}

When to use

Use this library if you want to fearlessly query and migrate your SQLite database with a Rusty API build on an encoding of your schema in types.

Here are some errors that rust-query can prevent at compile-time:

• Column type errors.
• Foreign key violations on insert/update.
• Mismatches in number of returned rows (zero, one or multiple).
• Use of undefined columns.
• SQL syntax errors.

Some other errors cannot be prevented at compile-time, but they can be turned into Result types so that the user is aware of them:

• Unique constraint errors.
• Foreign key violations on delete.

Next to those features, rust-query also helps writing complex queries:

• Reuse part of your query in another query by extracting it into a Rust function. Query types are kept simple so that the required function signature is easy to write.
• Aggregates that always return a single row make it easier to reason about queries.
• Automatic decorrelation of correlated sub-queries makes it possible to run those on SQLite.

When not to use

Do not use rust-query if you want a zero-cost abstraction. The focus of this project is on bringing errors to compile-time and generally making transactions easier to write.

Do not use rust-query migrations if you plan to keep those migrations around for a long time. Currently rust-query generates quite a bit of code for every version of your schema and migrations may need to be updated to work with a new breaking version of rust-query. Improving compatiblity with migrations managed by other tools is on the roadmap.

Note that this project is still in relatively early stages. There might be bugs to catch, so if you are worried about that, then don’t use this yet.

Roadmap

The current focus is on making the library more accessible and more generally useful. Funded by NLnet!

Modules

args

Types that are used as closure arguments.

migration

Types to declare schemas and migrations.

Structs

Database

Database is a proof that the database has been configured.

DatabaseAsync

This is an async wrapper for Database.

Expr

This is an expression that can be used in queries.

Lazy

Lazy can be used to read any column of a table row and its parents. Columns are loaded on demand, one row at at time.

Mutable

Mutable access to columns of a single table row.

Select

Select is used to define what to query from the database for each row.

TableRow

Row reference that can be used in any query in the same transaction.

Transaction

Transaction can be used to query and update the database.

TransactionWeak

This is the weak version of Transaction.

UnixEpochDeprecated

Use this a value in a query to get the current datetime as a number of seconds.

Update

Defines a column update.

Traits

FromExpr

Trait for values that can be retrieved from the database using one expression.

IntoExpr

Trait for all values that can be used as expressions in queries.

IntoSelect

This trait is implemented by everything that can be retrieved from the database.

Table

This trait is implemented for all table types as generated by the crate::migration::schema macro.

Functions

aggregate

Perform an aggregate that returns a single result for each of the current rows.

optional

This is a combinator function that allows constructing single row optional queries.

Derive Macros

FromExpr

Use in combination with #[rust_query(From = Thing)] to specify which tables this struct should implement FromExpr for.

Select

Derive Select to create a new *Select struct.