Struct TransactionBuilder

pub struct TransactionBuilder<'a, C> { /* private fields */ }

Available on crate feature postgres_backend only.

Used to build a transaction, specifying additional details.

This struct is returned by .build_transaction. See the documentation for methods on this struct for usage examples. See the PostgreSQL documentation for SET TRANSACTION for details on the behavior of each option.

Implementations

impl<'a, C> TransactionBuilder<'a, C>

where C: Connection<Backend = Pg, TransactionManager = AnsiTransactionManager>,

pub fn new(connection: &'a mut C) -> Self

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Creates a new TransactionBuilder.

pub fn read_only(self) -> Self

Makes the transaction READ ONLY

Example

conn.build_transaction()
    .read_only()
    .run::<_, diesel::result::Error, _>(|conn| {
        let read_attempt = users.select(name).load::<String>(conn);
        assert!(read_attempt.is_ok());

        let write_attempt = diesel::insert_into(users)
            .values(name.eq("Ruby"))
            .execute(conn);
        assert!(write_attempt.is_err());

        Ok(())
    })?;

pub fn read_write(self) -> Self

Makes the transaction READ WRITE

This is the default, unless you’ve changed the default_transaction_read_only configuration parameter.

Example

conn.build_transaction()
    .read_write()
    .run(|conn| {
        let read_attempt = users.select(name).load::<String>(conn);
        assert!(read_attempt.is_ok());

        let write_attempt = diesel::insert_into(users)
            .values(name.eq("Ruby"))
            .execute(conn);
        assert!(write_attempt.is_ok());

        Ok(())
    })

pub fn deferrable(self) -> Self

Makes the transaction DEFERRABLE

Example

conn.build_transaction()
    .deferrable()
    .run(|conn| Ok(()))

pub fn not_deferrable(self) -> Self

Makes the transaction NOT DEFERRABLE

This is the default, unless you’ve changed the default_transaction_deferrable configuration parameter.

Example

conn.build_transaction()
    .not_deferrable()
    .run(|conn| Ok(()))

pub fn read_committed(self) -> Self

Makes the transaction ISOLATION LEVEL READ COMMITTED

This is the default, unless you’ve changed the default_transaction_isolation_level configuration parameter.

Example

conn.build_transaction()
    .read_committed()
    .run(|conn| Ok(()))

pub fn repeatable_read(self) -> Self

Makes the transaction ISOLATION LEVEL REPEATABLE READ

Example

conn.build_transaction()
    .repeatable_read()
    .run(|conn| Ok(()))

pub fn serializable(self) -> Self

Makes the transaction ISOLATION LEVEL SERIALIZABLE

Example

conn.build_transaction()
    .serializable()
    .run(|conn| Ok(()))

pub fn run<T, E, F>(&mut self, f: F) -> Result<T, E>

where F: FnOnce(&mut C) -> Result<T, E>, E: From<Error>,

Runs the given function inside of the transaction with the parameters given to this builder.

This function executes the provided closure f inside a database transaction. If there is already an open transaction for the current connection it will return an error. The connection is committed if the closure returns Ok(_), it will be rolled back if it returns Err(_). For both cases the original result value will be returned from this function.

If the transaction fails to commit and requires a rollback according to Postgres, (e.g. serialization failure) a rollback will be attempted. If the rollback fails, the error will be returned in a Error::RollbackErrorOnCommit, from which you will be able to extract both the original commit error and the rollback error. In addition, the connection will be considered broken as it contains a uncommitted unabortable open transaction. Any further interaction with the transaction system will result in an returned error in this case.

Trait Implementations

impl<C> QueryFragment<Pg> for TransactionBuilder<'_, C>

fn walk_ast<'b>(&'b self, out: AstPass<'_, 'b, Pg>) -> QueryResult<()>

Walk over this QueryFragment for all passes.

fn to_sql(&self, out: &mut DB::QueryBuilder, backend: &DB) -> QueryResult<()>

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Converts this QueryFragment to its SQL representation.

fn collect_binds<'b>( &'b self, out: &mut DB::BindCollector<'b>, metadata_lookup: &mut DB::MetadataLookup, backend: &'b DB, ) -> QueryResult<()>

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Serializes all bind parameters in this query.

fn is_safe_to_cache_prepared(&self, backend: &DB) -> QueryResult<bool>

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Is this query safe to store in the prepared statement cache?

fn is_noop(&self, backend: &DB) -> QueryResult<bool>

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Does walking this AST have any effect?