Crate arminius_lib_db 

Arminius Database Layer

The common interface for application code to execute DB queries.

In essence, this crate contains three types:

• DefaultDb: executes queries outside of a transaction, can start a transaction.
• TransactedDb: executes queries inside of a transaction, can commit and roll back a transaction.
• Database: a trait implemented by both DefaultDb and TransactedDb.

This crate does not provide any queries by itself. These are meant to be added by other crates via extension traits on Database.

Writing queries

Conventions

Queries are meant to be defined in their own crate. The name of such crate should adhere to the pattern arminius-lib-db-<table>.

As a rule of thumb, one such crate should only be responsible for one specific table. This allows for fine-grained control over what components are allowed to execute which queries. However, there might be situations where we deviate from this and have more than one table managed by an extension crate, because they relate very close to each other (room and event being an example for such). However, we should not end up having multiple crates for one table.

Such crates should not depend on other crates, with the following exceptions:

• arminius-lib-db
• arminius-lib-model
• sqlx

SELECT queries should return their results using one of the types in arminius-lib-model, so that data is represented in a use case-agnostic way. This allows queries to be reused in different situations.

Registering queries via extension trait

Queries should be added as a trait:

/// the trait that contains the queries
// This annotation will suggest imports as _ (preferred for extension traits).
 #[rust_analyzer::prefer_underscore_import]
trait FooQueries : Database {
	// note that queries functions are not abstract
	async fn create_foo(&mut self, ...) -> Result<arminius_lib_model::FooId> {
		sqlx::query!("select ...").fetch_all(self.connection())
	}

	// more queries methods here....
}

Make queries available to Database trait via a blanket implementation:

impl<T: Database> ExampleQueries for T {}

Modules

query

Query utilities

Structs

DefaultDb

Default implementation that works without a transaction

RawPgConnection

We re-export some SQLX types, so these can be used A connection to a PostgreSQL database.

TransactedDb

DB Queries inside a transaction

Enums

DatabaseError

A generic Error type to be used for functions that perform DB operations.

Traits

Database

Provides access to a connection. Should be called by extension traits but not from application code.

ResultExt

Allows to convenient convert to a Result<T, DatabaseError::InvalidData>.

Type Aliases

RawPgTransaction

We re-export some SQLX types, so these can be used An alias for [Transaction][crate::transaction::Transaction], specialized for Postgres.