Struct TransactionScope 

pub struct TransactionScope { /* private fields */ }

Available on crate feature database and native only.

Transaction scope guard with automatic rollback on drop

This struct implements RAII (Resource Acquisition Is Initialization) pattern for database transactions. When the scope is dropped without explicit commit, it automatically rolls back the transaction.

Connection Affinity

TransactionScope holds a dedicated database connection that is used for all queries within the transaction. This ensures proper transaction isolation by guaranteeing that all operations (BEGIN, queries, COMMIT/ROLLBACK) run on the same physical connection.

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

// For doctest purposes, using mock connection (URL is ignored in current implementation)
let conn = DatabaseConnection::connect("postgres://localhost/test").await.unwrap();

// Transaction is automatically rolled back if not committed
{
    let mut tx = TransactionScope::begin(&conn).await.unwrap();
    // ... perform operations ...
    // If we don't call tx.commit(), rollback happens automatically
}

// Explicit commit
{
    let mut tx = TransactionScope::begin(&conn).await.unwrap();
    // ... perform operations ...
    tx.commit().await.unwrap(); // Explicit commit
}

Implementations

impl TransactionScope

pub async fn begin(conn: &DatabaseConnection) -> Result<TransactionScope, Error>

Begin a new transaction scope

This acquires a dedicated database connection and begins a transaction on it. All queries executed through this scope are guaranteed to run on the same physical connection, ensuring proper transaction isolation.

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

// For doctest purposes, using mock connection (URL is ignored in current implementation)
let conn = DatabaseConnection::connect("postgres://localhost/test").await.unwrap();
let mut tx = TransactionScope::begin(&conn).await.unwrap();
// ... perform operations ...
tx.commit().await.unwrap();

pub async fn begin_with_isolation( conn: &DatabaseConnection, level: IsolationLevel, ) -> Result<TransactionScope, Error>

Begin a new transaction scope with specific isolation level

This acquires a dedicated database connection and begins a transaction with the specified isolation level. All queries executed through this scope are guaranteed to run on the same physical connection.

Arguments

• conn - The database connection
• level - The desired isolation level for the transaction

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::{TransactionScope, IsolationLevel};

let conn = DatabaseConnection::connect("postgres://localhost/test").await.unwrap();
let mut tx = TransactionScope::begin_with_isolation(&conn, IsolationLevel::Serializable).await.unwrap();
// ... perform operations ...
tx.commit().await.unwrap();

pub async fn execute( &mut self, sql: &str, params: Vec<QueryValue>, ) -> Result<u64, Error>

Execute a SQL statement within the transaction

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

let conn = DatabaseConnection::connect("postgres://localhost/test").await.unwrap();
let mut tx = TransactionScope::begin(&conn).await.unwrap();

// Execute SQL within the transaction
tx.execute("INSERT INTO users (name) VALUES ($1)", vec!["Alice".into()]).await.unwrap();

tx.commit().await.unwrap();

pub async fn query_one( &mut self, sql: &str, params: Vec<QueryValue>, ) -> Result<QueryRow, Error>

Execute a SQL query and return a single row within the transaction

pub async fn query( &mut self, sql: &str, params: Vec<QueryValue>, ) -> Result<Vec<QueryRow>, Error>

Execute a SQL query and return all rows within the transaction

pub async fn query_optional( &mut self, sql: &str, params: Vec<QueryValue>, ) -> Result<Option<QueryRow>, Error>

Execute a SQL query and return an optional row within the transaction

pub async fn commit(self) -> Result<(), Error>

Commit the transaction

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

// For doctest purposes, using mock connection (URL is ignored in current implementation)
let conn = DatabaseConnection::connect("postgres://localhost/test").await.unwrap();
let mut tx = TransactionScope::begin(&conn).await.unwrap();
// ... perform operations ...
tx.commit().await.unwrap();

pub async fn rollback(self) -> Result<(), Error>

Explicit rollback

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

// For doctest purposes, using mock connection (URL is ignored in current implementation)
let conn = DatabaseConnection::connect("postgres://localhost/test").await.unwrap();
let mut tx = TransactionScope::begin(&conn).await.unwrap();
// ... error occurs ...
tx.rollback().await.unwrap();

pub async fn savepoint(&mut self, name: &str) -> Result<(), Error>

Create a savepoint within the transaction

Savepoints allow partial rollback of a transaction. You can create multiple savepoints and rollback to any of them without affecting work done before that savepoint.

Arguments

• name - The name of the savepoint

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

let conn = DatabaseConnection::connect("postgres://localhost/test").await?;
let mut tx = TransactionScope::begin(&conn).await?;

tx.execute("INSERT INTO users (name) VALUES ($1)", vec!["Alice".into()]).await?;

// Create a savepoint before risky operation
tx.savepoint("before_risky_op").await?;

// Perform risky operation
if let Err(_) = tx.execute("INSERT INTO users (name) VALUES ($1)", vec!["Invalid".into()]).await {
    // Rollback to savepoint, keeping Alice's insert
    tx.rollback_to_savepoint("before_risky_op").await?;
}

tx.commit().await?;

pub async fn release_savepoint(&mut self, name: &str) -> Result<(), Error>

Release a savepoint

Releasing a savepoint removes it from the transaction’s savepoint stack. This is typically done after the risky operation succeeded and the savepoint is no longer needed.

Arguments

• name - The name of the savepoint to release

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

let conn = DatabaseConnection::connect("postgres://localhost/test").await?;
let mut tx = TransactionScope::begin(&conn).await?;

tx.savepoint("sp1").await?;
// ... operations succeeded ...
tx.release_savepoint("sp1").await?;

tx.commit().await?;

pub async fn rollback_to_savepoint(&mut self, name: &str) -> Result<(), Error>

Rollback to a savepoint

This undoes all changes made after the savepoint was created, but keeps the transaction open for further operations.

Arguments

• name - The name of the savepoint to rollback to

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

let conn = DatabaseConnection::connect("postgres://localhost/test").await?;
let mut tx = TransactionScope::begin(&conn).await?;

tx.execute("INSERT INTO users (name) VALUES ($1)", vec!["Alice".into()]).await?;
tx.savepoint("sp1").await?;

// This will be rolled back
tx.execute("INSERT INTO users (name) VALUES ($1)", vec!["Bob".into()]).await?;

// Rollback to savepoint - Bob's insert is undone, Alice's remains
tx.rollback_to_savepoint("sp1").await?;

tx.commit().await?; // Only Alice is committed

pub async fn run<F, Fut, T>(self, f: F) -> Result<T, Error>

where F: FnOnce(&mut TransactionScope) -> Fut, Fut: Future<Output = Result<T, Error>>,

Execute a closure and automatically commit on success or rollback on error

This method provides a closure-based API for executing operations within the transaction scope. The transaction is automatically committed if the closure returns Ok, or rolled back if it returns Err.

Examples

use reinhardt_db::orm::connection::DatabaseConnection;
use reinhardt_db::orm::transaction::TransactionScope;

let conn = DatabaseConnection::connect("sqlite::memory:").await?;
let mut tx = TransactionScope::begin(&conn).await?;

let result = tx.run(|tx| async move {
    // Perform operations via tx.execute(), tx.query(), etc.
    Ok(42)
}).await?;

assert_eq!(result, 42);

Trait Implementations

impl Drop for TransactionScope

fn drop(&mut self)

Automatically rollback transaction if not committed

This ensures that transactions are always cleaned up, even if an error occurs or the scope is exited early.

Note

When using TransactionScope directly (not through transaction() function), it’s recommended to explicitly call commit() or rollback() to handle errors properly. The automatic rollback in Drop cannot propagate errors.

The automatic rollback in Drop requires a multi-threaded tokio runtime. For single-threaded runtimes or when no runtime is available, only a warning message is printed.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.