Struct postgres::Connection

pub struct Connection(_);

A connection to a Postgres database.

Methods

impl Connection

fn connect<T>(params: T, tls: TlsMode) -> Result<Connection> where
    T: IntoConnectParams, 

Creates a new connection to a Postgres database.

Most applications can use a URL string in the normal format:

postgresql://user[:password]@host[:port][/database][?param1=val1[[&param2=val2]...]]

The password may be omitted if not required. The default Postgres port (5432) is used if none is specified. The database name defaults to the username if not specified.

To connect to the server via Unix sockets, host should be set to the absolute path of the directory containing the socket file. Since / is a reserved character in URLs, the path should be URL encoded. If the path contains non-UTF 8 characters, a ConnectParams struct should be created manually and passed in. Note that Postgres does not support TLS over Unix sockets.

Examples

To connect over TCP:

use postgres::{Connection, TlsMode};

let url = "postgresql://postgres:hunter2@localhost:5433:2994/foodb";
let conn = Connection::connect(url, TlsMode::None).unwrap();

To connect over a Unix socket located in /run/postgres:

use postgres::{Connection, TlsMode};

let url = "postgresql://postgres@%2Frun%2Fpostgres";
let conn = Connection::connect(url, TlsMode::None).unwrap();

To connect with a manually constructed ConnectParams:

use postgres::{Connection, TlsMode};
use postgres::params::{ConnectParams, Host};

let params = ConnectParams::builder()
    .user("postgres", None)
    .build(Host::Unix(some_crazy_path));
let conn = Connection::connect(params, TlsMode::None).unwrap();

fn execute(&self, query: &str, params: &[&ToSql]) -> Result<u64>

Executes a statement, returning the number of rows modified.

A statement may contain parameters, specified by $n where n is the index of the parameter in the list provided, 1-indexed.

If the statement does not modify any rows (e.g. SELECT), 0 is returned.

If the same statement will be repeatedly executed (perhaps with different query parameters), consider using the prepare and prepare_cached methods.

Panics

Panics if the number of parameters provided does not match the number expected.

Example

let rows_updated = conn.execute("UPDATE foo SET bar = $1 WHERE baz = $2", &[&bar, &baz])
                       .unwrap();
println!("{} rows updated", rows_updated);

fn query(&self, query: &str, params: &[&ToSql]) -> Result<Rows>

Executes a statement, returning the resulting rows.

A statement may contain parameters, specified by $n where n is the index of the parameter in the list provided, 1-indexed.

If the same statement will be repeatedly executed (perhaps with different query parameters), consider using the prepare and prepare_cached methods.

Panics

Panics if the number of parameters provided does not match the number expected.

Example

for row in &conn.query("SELECT foo FROM bar WHERE baz = $1", &[&baz]).unwrap() {
    let foo: i32 = row.get("foo");
    println!("foo: {}", foo);
}

fn transaction<'a>(&'a self) -> Result<Transaction<'a>>

Begins a new transaction.

Returns a Transaction object which should be used instead of the connection for the duration of the transaction. The transaction is active until the Transaction object falls out of scope.

Note

A transaction will roll back by default. The set_commit, set_rollback, and commit methods alter this behavior.

Panics

Panics if a transaction is already active.

Example

let trans = conn.transaction().unwrap();
trans.execute("UPDATE foo SET bar = 10", &[]).unwrap();
// ...

trans.commit().unwrap();

fn transaction_with<'a>(&'a self, config: &Config) -> Result<Transaction<'a>>

Begins a new transaction with the specified configuration.

fn prepare<'a>(&'a self, query: &str) -> Result<Statement<'a>>

Creates a new prepared statement.

If the same statement will be executed repeatedly, explicitly preparing it can improve performance.

The statement is associated with the connection that created it and may not outlive that connection.

Example

let stmt = conn.prepare("UPDATE foo SET bar = $1 WHERE baz = $2").unwrap();
for (bar, baz) in updates {
    stmt.execute(&[bar, baz]).unwrap();
}

fn prepare_cached<'a>(&'a self, query: &str) -> Result<Statement<'a>>

Creates a cached prepared statement.

Like prepare, except that the statement is only prepared once over the lifetime of the connection and then cached. If the same statement is going to be prepared frequently, caching it can improve performance by reducing the number of round trips to the Postgres backend.

Example

let stmt = conn.prepare_cached("UPDATE foo SET bar = $1 WHERE baz = $2").unwrap();
for (bar, baz) in updates {
    stmt.execute(&[bar, baz]).unwrap();
}

fn transaction_isolation(&self) -> Result<IsolationLevel>

Returns the isolation level which will be used for future transactions.

This is a simple wrapper around SHOW TRANSACTION ISOLATION LEVEL.

fn set_transaction_config(&self, config: &Config) -> Result<()>

Sets the configuration that will be used for future transactions.

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

Execute a sequence of SQL statements.

Statements should be separated by ; characters. If an error occurs, execution of the sequence will stop at that point. This is intended for execution of batches of non-dynamic statements - for example, creation of a schema for a fresh database.

Warning

Prepared statements should be used for any SQL statement which contains user-specified data, as it provides functionality to safely embed that data in the statement. Do not form statements via string concatenation and feed them into this method.

Example

conn.batch_execute("
    CREATE TABLE person (
        id SERIAL PRIMARY KEY,
        name NOT NULL
    );

    CREATE TABLE purchase (
        id SERIAL PRIMARY KEY,
        person INT NOT NULL REFERENCES person (id),
        time TIMESTAMPTZ NOT NULL,
    );

    CREATE INDEX ON purchase (time);
    ").unwrap();

fn notifications<'a>(&'a self) -> Notifications<'a>

Returns a structure providing access to asynchronous notifications.

Use the LISTEN command to register this connection for notifications.

fn cancel_data(&self) -> CancelData

Returns information used to cancel pending queries.

Used with the cancel_query function. The object returned can be used to cancel any query executed by the connection it was created from.

fn parameter(&self, param: &str) -> Option<String>

Returns the value of the specified Postgres backend parameter, such as timezone or server_version.

fn set_notice_handler(&self, handler: Box<HandleNotice>) -> Box<HandleNotice>

Sets the notice handler for the connection, returning the old handler.

fn is_desynchronized(&self) -> bool

Returns whether or not the stream has been desynchronized due to an error in the communication channel with the server.

If this has occurred, all further queries will immediately return an error.

fn is_active(&self) -> bool

Determines if the Connection is currently "active", that is, if there are no active transactions.

The transaction method can only be called on the active Connection or Transaction.

fn finish(self) -> Result<()>

Consumes the connection, closing it.

Functionally equivalent to the Drop implementation for Connection except that it returns any error encountered to the caller.

Trait Implementations

impl Debug for Connection

fn fmt(&self, fmt: &mut Formatter) -> Result

Formats the value using the given formatter.

impl GenericConnection for Connection

fn execute(&self, query: &str, params: &[&ToSql]) -> Result<u64>

Like Connection::execute.

fn query<'a>(&'a self, query: &str, params: &[&ToSql]) -> Result<Rows>

Like Connection::query.

fn prepare<'a>(&'a self, query: &str) -> Result<Statement<'a>>

Like Connection::prepare.

fn prepare_cached<'a>(&'a self, query: &str) -> Result<Statement<'a>>

Like Connection::prepare_cached.

fn transaction<'a>(&'a self) -> Result<Transaction<'a>>

Like Connection::transaction.

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

Like Connection::batch_execute.

fn is_active(&self) -> bool

Like Connection::is_active.