Struct PgConnection 

pub struct PgConnection { /* private fields */ }

The connection string expected by PgConnection::establish should be a PostgreSQL connection string, as documented at https://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNSTRING

Supported loading model implementations

• DefaultLoadingMode
• PgRowByRowLoadingMode

If you are unsure which loading mode is the correct one for your application, you likely want to use the DefaultLoadingMode as that one offers generally better performance.

Due to the fact that PgConnection supports multiple loading modes it is required to always specify the used loading mode when calling RunQueryDsl::load_iter

DefaultLoadingMode

By using this mode PgConnection defaults to loading all response values at once and only performs deserialization afterward for the DefaultLoadingMode. Generally this mode will be more performant as it.

This loading mode allows users to perform hold more than one iterator at once using the same connection:

use diesel::connection::DefaultLoadingMode;

let iter1 = users::table.load_iter::<(i32, String), DefaultLoadingMode>(connection)?;
let iter2 = users::table.load_iter::<(i32, String), DefaultLoadingMode>(connection)?;

for r in iter1 {
    let (id, name) = r?;
    println!("Id: {} Name: {}", id, name);
}

for r in iter2 {
    let (id, name) = r?;
    println!("Id: {} Name: {}", id, name);
}

PgRowByRowLoadingMode

By using this mode PgConnection defaults to loading each row of the result set separately. This might be desired for huge result sets.

This loading mode prevents creating more than one iterator at once using the same connection. The following code is not allowed:

use diesel::pg::PgRowByRowLoadingMode;

let iter1 = users::table.load_iter::<(i32, String), PgRowByRowLoadingMode>(connection)?;
// creating a second iterator generates an compiler error
let iter2 = users::table.load_iter::<(i32, String), PgRowByRowLoadingMode>(connection)?;

for r in iter1 {
    let (id, name) = r?;
    println!("Id: {} Name: {}", id, name);
}

for r in iter2 {
    let (id, name) = r?;
    println!("Id: {} Name: {}", id, name);
}

Implementations

impl PgConnection

pub fn build_transaction(&mut self) -> TransactionBuilder<'_, PgConnection>

Build a transaction, specifying additional details such as isolation level

See TransactionBuilder for more examples.

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

pub fn notifications_iter( &mut self, ) -> impl Iterator<Item = Result<PgNotification, Error>>

See Postgres documentation for SQL commands NOTIFY and LISTEN

The returned iterator can yield items even after a None value when new notifications have been received. The iterator can be polled again after a None value was received as new notifications might have been send in the mean time.

Example

// register the notifications channel we want to receive notifications for
diesel::sql_query("LISTEN example_channel").execute(connection)?;
// send some notification
// this is usually done from a different connection/thread/application
diesel::sql_query("NOTIFY example_channel, 'additional data'").execute(connection)?;

for result in connection.notifications_iter() {
    let notification = result.unwrap();
    assert_eq!(notification.channel, "example_channel");
    assert_eq!(notification.payload, "additional data");

    println!(
        "Notification received from server process with id {}.",
        notification.process_id
    );
}

Trait Implementations

impl Connection for PgConnection

type Backend = Pg

The backend this type connects to

fn establish(database_url: &str) -> Result<PgConnection, ConnectionError>

Establishes a new connection to the database

fn set_instrumentation(&mut self, instrumentation: impl Instrumentation)

Set a specific Instrumentation implementation for this connection

fn set_prepared_statement_cache_size(&mut self, size: CacheSize)

Set the prepared statement cache size to CacheSize for this connection

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

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

Executes the given function inside of a database transaction

fn begin_test_transaction(&mut self) -> Result<(), Error>

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

fn test_transaction<T, E, F>(&mut self, f: F) -> T

where F: FnOnce(&mut Self) -> 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.

impl<T, A> ExecuteCopyFromDsl<PgConnection> for CopyFromQuery<T, A>

where A: CopyFromExpression<T>,

type Error = <A as CopyFromExpression<T>>::Error

The error type returned by the execute function

fn execute( self, conn: &mut PgConnection, ) -> Result<usize, <A as CopyFromExpression<T>>::Error>

See the trait documentation for details

impl<B> LoadConnection<B> for PgConnection

where PgConnection: PgLoadingMode<B>,

type Cursor<'conn, 'query> = <PgConnection as PgLoadingMode<B>>::Cursor<'conn, 'query>

The cursor type returned by LoadConnection::load

type Row<'conn, 'query> = <PgConnection as PgLoadingMode<B>>::Row<'conn, 'query>

The row type used as Iterator::Item for the iterator implementation of LoadConnection::Cursor

impl MigrationConnection for PgConnection

fn setup(&mut self) -> Result<usize, Error>

Setup the following table:

impl SimpleConnection for PgConnection

fn batch_execute(&mut self, query: &str) -> Result<(), Error>

Execute multiple SQL statements within the same string.

impl<'b, Changes, Output> UpdateAndFetchResults<Changes, Output> for PgConnection

where Changes: Copy + AsChangeset<Target = <Changes as HasTable>::Table> + IntoUpdateTarget, UpdateStatement<<Changes as HasTable>::Table, <Changes as IntoUpdateTarget>::WhereClause, <Changes as AsChangeset>::Changeset>: LoadQuery<'b, PgConnection, Output>, <<Changes as HasTable>::Table as Table>::AllColumns: ValidGrouping<()>, <<<Changes as HasTable>::Table as Table>::AllColumns as ValidGrouping<()>>::IsAggregate: MixedAggregates<No, Output = No>,

fn update_and_fetch(&mut self, changeset: Changes) -> Result<Output, Error>

See the traits documentation.

impl Send for PgConnection