Struct PgConnection

pub struct PgConnection { /* private fields */ }

Available on crate feature postgres only.

A connection to a PostgreSQL database.

Implementations

impl PgConnection

pub fn server_version_num(&self) -> Option<u32>

the version number of the server in libpq format

impl PgConnection

pub async fn copy_in_raw( &mut self, statement: &str, ) -> Result<PgCopyIn<&mut PgConnection>, Error>

Issue a COPY FROM STDIN statement and transition the connection to streaming data to Postgres. This is a more efficient way to import data into Postgres as compared to INSERT but requires one of a few specific data formats (text/CSV/binary).

If statement is anything other than a COPY ... FROM STDIN ... command, an error is returned.

Command examples and accepted formats for COPY data are shown here: https://www.postgresql.org/docs/current/sql-copy.html

Note

PgCopyIn::finish or PgCopyIn::abort must be called when finished or the connection will return an error the next time it is used.

pub async fn copy_out_raw<'c>( &'c mut self, statement: &str, ) -> Result<Pin<Box<dyn Stream<Item = Result<Bytes, Error>> + Send + 'c>>, Error>

Issue a COPY TO STDOUT statement and transition the connection to streaming data from Postgres. This is a more efficient way to export data from Postgres but arrives in chunks of one of a few data formats (text/CSV/binary).

If statement is anything other than a COPY ... TO STDOUT ... command, an error is returned.

Note that once this process has begun, unless you read the stream to completion, it can only be canceled in two ways:

1. by closing the connection, or:
2. by using another connection to kill the server process that is sending the data as shown in this StackOverflow answer.

If you don’t read the stream to completion, the next time the connection is used it will need to read and discard all the remaining queued data, which could take some time.

Command examples and accepted formats for COPY data are shown here: https://www.postgresql.org/docs/current/sql-copy.html

Trait Implementations

impl<'c> Acquire<'c> for &'c mut PgConnection

type Database = Postgres

type Connection = &'c mut <Postgres as Database>::Connection

fn acquire( self, ) -> Pin<Box<dyn Future<Output = Result<<&'c mut PgConnection as Acquire<'c>>::Connection, Error>> + Send + 'c>>

fn begin( self, ) -> Pin<Box<dyn Future<Output = Result<Transaction<'c, Postgres>, Error>> + Send + 'c>>

impl AnyConnectionBackend for PgConnection

fn name(&self) -> &str

The backend name.

fn close( self: Box<PgConnection>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>

Explicitly close this database connection.

fn ping( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Checks if a connection to the database is still valid.

fn begin( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Begin a new transaction or establish a savepoint within the active transaction.

fn commit( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

fn rollback( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

fn start_rollback(&mut self)

fn shrink_buffers(&mut self)

Forward to Connection::shrink_buffers().

fn as_migrate(&mut self) -> Result<&mut (dyn Migrate + Send + 'static), Error>

fn fetch_many<'q>( &'q mut self, query: &'q str, arguments: Option<AnyArguments<'q>>, ) -> Pin<Box<dyn Stream<Item = Result<Either<AnyQueryResult, AnyRow>, Error>> + Send + 'q>>

fn fetch_optional<'q>( &'q mut self, query: &'q str, arguments: Option<AnyArguments<'q>>, ) -> Pin<Box<dyn Future<Output = Result<Option<AnyRow>, Error>> + Send + 'q>>

fn prepare_with<'c, 'q>( &'c mut self, sql: &'q str, _parameters: &[AnyTypeInfo], ) -> Pin<Box<dyn Future<Output = Result<AnyStatement<'q>, Error>> + Send + 'c>>

where 'q: 'c,

fn describe<'q>( &'q mut self, sql: &'q str, ) -> Pin<Box<dyn Future<Output = Result<Describe<Any>, Error>> + Send + 'q>>

fn cached_statements_size(&self) -> usize

The number of statements currently cached in the connection.

fn clear_cached_statements( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Removes all statements from the cache, closing them on the server if needed.

impl<'lock, C> AsMut<PgConnection> for PgAdvisoryLockGuard<'lock, C>

where C: AsMut<PgConnection>,

Mutable access to the underlying connection is provided so it can still be used like normal, even allowing locks to be taken recursively.

However, replacing the connection with a different one using, e.g. std::mem::replace() is a logic error and will cause a warning to be logged by the PostgreSQL server when this guard attempts to release the lock.

fn as_mut(&mut self) -> &mut PgConnection

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsMut<PgConnection> for PgConnection

fn as_mut(&mut self) -> &mut PgConnection

Converts this type into a mutable reference of the (usually inferred) input type.

impl<'lock, C> AsRef<PgConnection> for PgAdvisoryLockGuard<'lock, C>

where C: AsMut<PgConnection> + AsRef<PgConnection>,

fn as_ref(&self) -> &PgConnection

Converts this type into a shared reference of the (usually inferred) input type.

impl Connection for PgConnection

type Database = Postgres

type Options = PgConnectOptions

fn close(self) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>

Explicitly close this database connection.

fn ping( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Checks if a connection to the database is still valid.

fn begin( &mut self, ) -> Pin<Box<dyn Future<Output = Result<Transaction<'_, <PgConnection as Connection>::Database>, Error>> + Send + '_>>

where PgConnection: Sized,

Begin a new transaction or establish a savepoint within the active transaction.

fn cached_statements_size(&self) -> usize

The number of statements currently cached in the connection.

fn clear_cached_statements( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Removes all statements from the cache, closing them on the server if needed.

fn shrink_buffers(&mut self)

Restore any buffers in the connection to their default capacity, if possible.

fn transaction<'a, F, R, E>( &'a mut self, callback: F, ) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'a>>

where F: for<'c> FnOnce(&'c mut Transaction<'_, Self::Database>) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'c>> + 'a + for<'c> Send + for<'c> Sync, Self: Sized, R: Send, E: From<Error> + Send,

Execute the function inside a transaction.

fn connect( url: &str, ) -> Pin<Box<dyn Future<Output = Result<Self, Error>> + Send>>

where Self: Sized,

Establish a new database connection.

fn connect_with( options: &Self::Options, ) -> Pin<Box<dyn Future<Output = Result<Self, Error>> + Send + '_>>

where Self: Sized,

Establish a new database connection with the provided options.

impl Debug for PgConnection

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'c> Executor<'c> for &'c mut PgConnection

type Database = Postgres

fn fetch_many<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Stream<Item = Result<Either<PgQueryResult, PgRow>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, <&'c mut PgConnection as Executor<'c>>::Database>,

Execute multiple queries and return the generated results as a stream from each query, in a stream.

fn fetch_optional<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<Option<PgRow>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, <&'c mut PgConnection as Executor<'c>>::Database>,

Execute the query and returns at most one row.

fn prepare_with<'e, 'q>( self, sql: &'q str, parameters: &'e [PgTypeInfo], ) -> Pin<Box<dyn Future<Output = Result<PgStatement<'q>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e,

Prepare the SQL query, with parameter type information, to inspect the type information about its parameters and results.

fn execute<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::QueryResult, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return the total number of rows affected.

fn execute_many<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::QueryResult, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute multiple queries and return the rows affected from each query, in a stream.

fn fetch<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return the generated results as a stream.

fn fetch_all<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<Vec<<Self::Database as Database>::Row>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return all the generated results, collected into a Vec.

fn fetch_one<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and returns exactly one row.

fn prepare<'e, 'q>( self, query: &'q str, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as HasStatement<'q>>::Statement, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e,

Prepare the SQL query to inspect the type information of its parameters and results.

impl Migrate for PgConnection

fn ensure_migrations_table( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), MigrateError>> + Send + '_>>

fn dirty_version( &mut self, ) -> Pin<Box<dyn Future<Output = Result<Option<i64>, MigrateError>> + Send + '_>>

fn list_applied_migrations( &mut self, ) -> Pin<Box<dyn Future<Output = Result<Vec<AppliedMigration>, MigrateError>> + Send + '_>>

fn lock( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), MigrateError>> + Send + '_>>

fn unlock( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), MigrateError>> + Send + '_>>

fn apply<'e, 'm>( &'e mut self, migration: &'m Migration, ) -> Pin<Box<dyn Future<Output = Result<Duration, MigrateError>> + Send + 'm>>

where 'e: 'm,

fn revert<'e, 'm>( &'e mut self, migration: &'m Migration, ) -> Pin<Box<dyn Future<Output = Result<Duration, MigrateError>> + Send + 'm>>

where 'e: 'm,