diesel::connection

Trait Connection

Source 
pub trait Connection:
    SimpleConnection
    + Sized
    + Send {
    type Backend: Backend;

    // Required method
    fn establish(database_url: &str) -> ConnectionResult<Self>;

    // Provided methods
    fn transaction<T, E, F>(&self, f: F) -> Result<T, E>
       where F: FnOnce() -> Result<T, E>,
             E: From<Error> { ... }
    fn begin_test_transaction(&self) -> QueryResult<()> { ... }
    fn test_transaction<T, E, F>(&self, f: F) -> T
       where F: FnOnce() -> Result<T, E>,
             E: Debug { ... }
}
Expand description

A connection to a database

Required Associated Types§

Source

type Backend: Backend

The backend this type connects to

Required Methods§

Source

fn establish(database_url: &str) -> ConnectionResult<Self>

Establishes a new connection to the database

The argument to this method varies by backend. See the documentation for that backend’s connection class for details about what it accepts.

Provided Methods§

Source

fn transaction<T, E, F>(&self, f: F) -> Result<T, E>
where F: FnOnce() -> Result<T, E>, E: From<Error>,

Executes the given function inside of a database transaction

If there is already an open transaction, savepoints will be used instead.

If the transaction fails to commit due to a SerializationFailure, a rollback will be attempted. If the rollback succeeds, the original error will be returned, otherwise the error generated by the rollback will be returned. In the second case the connection should be considered broken as it contains a uncommitted unabortable open transaction.

§Example
use diesel::result::Error;

conn.transaction::<_, Error, _>(|| {
    diesel::insert_into(users)
        .values(name.eq("Ruby"))
        .execute(&conn)?;

    let all_names = users.select(name).load::<String>(&conn)?;
    assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);

    Ok(())
})?;

conn.transaction::<(), _, _>(|| {
    diesel::insert_into(users)
        .values(name.eq("Pascal"))
        .execute(&conn)?;

    let all_names = users.select(name).load::<String>(&conn)?;
    assert_eq!(vec!["Sean", "Tess", "Ruby", "Pascal"], all_names);

    // If we want to roll back the transaction, but don't have an
    // actual error to return, we can return `RollbackTransaction`.
    Err(Error::RollbackTransaction)
});

let all_names = users.select(name).load::<String>(&conn)?;
assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);
Source

fn begin_test_transaction(&self) -> QueryResult<()>

Creates a transaction that will never be committed. This is useful for tests. Panics if called while inside of a transaction.

Source

fn test_transaction<T, E, F>(&self, f: F) -> T
where F: FnOnce() -> Result<T, E>, E: Debug,

Executes the given function inside a transaction, but does not commit it. Panics if the given function returns an error.

§Example
use diesel::result::Error;

conn.test_transaction::<_, Error, _>(|| {
    diesel::insert_into(users)
        .values(name.eq("Ruby"))
        .execute(&conn)?;

    let all_names = users.select(name).load::<String>(&conn)?;
    assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);

    Ok(())
});

// Even though we returned `Ok`, the transaction wasn't committed.
let all_names = users.select(name).load::<String>(&conn)?;
assert_eq!(vec!["Sean", "Tess"], all_names);

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§