Struct Connection

pub struct Connection { /* private fields */ }

Implementations

impl Connection

Asynchronous Command Processing

pub fn send_query(&self, command: &str) -> Result

Submits a command to the server without waiting for the result(s).

See PQsendQuery.

pub fn send_query_params( &self, command: &str, param_types: &[Oid], param_values: &[Option<&[u8]>], param_formats: &[Format], result_format: Format, ) -> Result

Submits a command and separate parameters to the server without waiting for the result(s).

See PQsendQueryParams.

pub fn send_prepare( &self, name: Option<&str>, query: &str, param_types: &[Oid], ) -> Result

Sends a request to create a prepared statement with the given parameters, without waiting for completion.

See PQsendPrepare.

pub fn send_query_prepared( &self, name: Option<&str>, param_values: &[Option<&[u8]>], param_formats: &[Format], result_format: Format, ) -> Result

Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).

See PQsendQueryPrepared.

pub fn send_describe_prepared(&self, name: Option<&str>) -> Result

Submits a request to obtain information about the specified prepared statement, without waiting for completion.

See PQsendDescribePortal.

pub fn send_describe_portal(&self, name: Option<&str>) -> Result

Submits a request to obtain information about the specified portal, without waiting for completion.

See PQsendDescribePortal.

pub fn result(&self) -> Option<PQResult>

Waits for the next result a prior send_* call, and returns it.

See PQgetResult.

pub fn consume_input(&self) -> Result

If input is available from the server, consume it.

See PQconsumeInput.

Examples found in repository

examples/testlibpq2.rs (line 78)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Issue LISTEN command to enable notifications from the rule's NOTIFY.
     */
    let res = conn.exec("LISTEN TBL2");
    if res.status() != libpq::Status::CommandOk {
        panic!("LISTEN command failed: {:?}", conn.error_message());
    }

    /* Quit after four notifies are received. */
    let mut nnotifies = 0;

    let sock = conn.socket()?;

    let mut poll = mio::Poll::new()?;
    let mut events = mio::Events::with_capacity(1);
    poll.registry().register(
        &mut mio::unix::SourceFd(&sock),
        mio::Token(0),
        mio::Interest::READABLE,
    )?;

    while nnotifies < 4 {
        /*
         * Sleep until something happens on the connection.
         */
        poll.poll(&mut events, None)?;

        /* Now check for input */
        conn.consume_input()?;
        while let Some(notify) = conn.notifies() {
            eprintln!(
                "ASYNC NOTIFY of '{}' received from backend PID {}",
                notify.relname()?,
                notify.be_pid()
            );
            nnotifies += 1;
            conn.consume_input()?;
        }
    }

    eprintln!("Done.");

    Ok(())
}

pub fn is_busy(&self) -> bool

Returns true if a command is busy, that is, Result would block waiting for input.

See PQisBusy.

pub fn set_non_blocking(&self, non_blocking: bool) -> Result

Sets the nonblocking status of the connection.

See PQsetnonblocking.

pub fn is_non_blocking(&self) -> bool

Returns the blocking status of the database connection.

See PQisnonblocking.

pub fn flush(&self) -> Result

Attempts to flush any queued output data to the server.

See PQflush.

impl Connection

Canceling Queries in Progress

pub fn cancel(&self) -> Cancel

Creates a data structure containing the information needed to cancel a command issued through a particular database connection.

See PQgetCancel.

impl Connection

Database Connection Control Functions

pub fn new(dsn: &str) -> Result<Self>

Makes a new connection to the database server.

See PQconnectdb.

Examples found in repository

examples/testlibpq2.rs (line 42)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Issue LISTEN command to enable notifications from the rule's NOTIFY.
     */
    let res = conn.exec("LISTEN TBL2");
    if res.status() != libpq::Status::CommandOk {
        panic!("LISTEN command failed: {:?}", conn.error_message());
    }

    /* Quit after four notifies are received. */
    let mut nnotifies = 0;

    let sock = conn.socket()?;

    let mut poll = mio::Poll::new()?;
    let mut events = mio::Events::with_capacity(1);
    poll.registry().register(
        &mut mio::unix::SourceFd(&sock),
        mio::Token(0),
        mio::Interest::READABLE,
    )?;

    while nnotifies < 4 {
        /*
         * Sleep until something happens on the connection.
         */
        poll.poll(&mut events, None)?;

        /* Now check for input */
        conn.consume_input()?;
        while let Some(notify) = conn.notifies() {
            eprintln!(
                "ASYNC NOTIFY of '{}' received from backend PID {}",
                notify.relname()?,
                notify.be_pid()
            );
            nnotifies += 1;
            conn.consume_input()?;
        }
    }

    eprintln!("Done.");

    Ok(())
}

examples/testlibpq.rs (line 17)

fn main() -> libpq::errors::Result {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    /* Make a connection to the database */
    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Our test case here involves using a cursor, for which we must be inside
     * a transaction block.  We could do the whole thing with a single
     * PQexec() of "select * from pg_database", but that's too trivial to make
     * a good example.
     */

    /* Start a transaction block */
    let res = conn.exec("BEGIN");
    if res.status() != libpq::Status::CommandOk {
        panic!("BEGIN command failed: {:?}", conn.error_message());
    }

    /*
     * Fetch rows from pg_database, the system catalog of databases
     */
    let res = conn.exec("DECLARE myportal CURSOR FOR select * from pg_database");
    if res.status() != libpq::Status::CommandOk {
        panic!("DECLARE CURSOR failed: {:?}", conn.error_message());
    }

    let res = conn.exec("FETCH ALL in myportal");
    if res.status() != libpq::Status::TuplesOk {
        panic!("FETCH ALL failed: {:?}", conn.error_message());
    }

    /* first, print out the attribute names */
    let nfields = res.nfields();
    for i in 0..nfields {
        print!("{:15}", res.field_name(i)?.unwrap_or_default());
    }
    println!("\n");

    /* next, print out the rows */
    for i in 0..res.ntuples() {
        for j in 0..nfields {
            let s = res
                .value(i, j)
                .map(|x| String::from_utf8(x.to_vec()).unwrap())
                .unwrap_or_default();
            print!("{s:15}");
        }
        println!();
    }

    /* close the portal ... we don't bother to check for errors ... */
    conn.exec("CLOSE myportal");

    /* end the transaction */
    conn.exec("END");

    Ok(())
}

examples/testlibpq3.rs (line 44)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    /* Make a connection to the database */
    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SET search_path = testlibpq3");
    if res.status() != libpq::Status::CommandOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * The point of this program is to illustrate use of PQexecParams() with
     * out-of-line parameters, as well as binary transmission of data.
     *
     * This first example transmits the parameters as text, but receives the
     * results in binary format.  By using out-of-line parameters we can avoid
     * a lot of tedious mucking about with quoting and escaping, even though
     * the data is text.  Notice how we don't have to do anything special with
     * the quote mark in the parameter value.
     */

    /* Here is our out-of-line parameter value */
    let param_values = [Some("joe's place\0".as_bytes())];

    let res = conn.exec_params(
        "SELECT * FROM test1 WHERE t = $1",
        &[], /* let the backend deduce param type */
        param_values.as_slice(),
        &[],                   /* default to all text params */
        libpq::Format::Binary, /* ask for binary results */
    );

    if res.status() != libpq::Status::TuplesOk {
        panic!("SELECT failed: {:?}", conn.error_message());
    }

    show_binary_results(&res)?;

    /*
     * In this second example we transmit an integer parameter in binary form,
     * and again retrieve the results in binary form.
     *
     * Although we tell PQexecParams we are letting the backend deduce
     * parameter type, we really force the decision by casting the parameter
     * symbol in the query text.  This is a good safety measure when sending
     * binary parameters.
     */

    /* Convert integer value "2" to network byte order */
    let binary_int_val = htonl(2);

    /* Set up parameter arrays for PQexecParams */
    let param_values = [Some(binary_int_val.as_slice())];
    let param_formats = vec![libpq::Format::Binary];

    let res = conn.exec_params(
        "SELECT * FROM test1 WHERE i = $1::int4",
        &[], /* let the backend deduce param type */
        &param_values,
        &param_formats,
        libpq::Format::Binary, /* ask for binary results */
    );

    if res.status() != libpq::Status::TuplesOk {
        panic!("SELECT failed: {:?}", conn.error_message());
    }

    show_binary_results(&res)?;

    Ok(())
}

pub fn with_params( params: &HashMap<&str, &str>, expand_dbname: bool, ) -> Result<Self>

Makes a new connection to the database server.

See PQconnectdbParams.

pub fn start(conninfo: &str) -> Result<Self>

Make a connection to the database server in a nonblocking manner.

See PQconnectStart.

pub fn start_params( params: &HashMap<String, String>, expand_dbname: bool, ) -> Result<Self>

Make a connection to the database server in a nonblocking manner.

See PQconnectStartParams.

pub fn set_db( host: Option<&str>, port: Option<&str>, options: Option<&str>, tty: Option<&str>, db_name: Option<&str>, ) -> Result<Self>

Makes a new connection to the database server.

See PQsetdb.

Examples found in repository

examples/testlo.rs (line 24)

fn main() -> libpq::errors::Result {
    let mut args = std::env::args();

    if args.len() < 4 {
        panic!(
            "usage: {} database_name in_filename out_filename",
            args.next().unwrap()
        );
    }

    let database = args.nth(1).unwrap();
    let in_filename = args.next().unwrap();
    let out_filename = args.next().unwrap();

    /*
     * set up the connection
     */
    let conn = libpq::Connection::set_db(None, None, None, None, Some(&database))?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    conn.exec("begin");
    println!("importing file \"{in_filename}\" ...");
    let lobj_oid = libpq::lo::import(&conn, &in_filename);

    println!("\tas large object {lobj_oid}.");

    println!("picking out bytes 1000-2000 of the large object");
    pickout(&conn, lobj_oid, 1_000, 1_000)?;

    println!("overwriting bytes 1000-2000 of the large object with X's");
    overwrite(&conn, lobj_oid, 1_000, 1_000)?;

    println!("exporting large object to file \"{out_filename}\" ...");
    libpq::lo::export(&conn, &out_filename, lobj_oid)?;

    conn.exec("end");

    Ok(())
}

examples/testlo64.rs (line 25)

fn main() -> libpq::errors::Result {
    let mut args = std::env::args();

    if args.len() < 5 {
        panic!(
            "usage: {} database_name in_filename out_filename out_filename2",
            args.next().unwrap()
        );
    }

    let database = args.nth(1).unwrap();
    let in_filename = args.next().unwrap();
    let out_filename = args.next().unwrap();
    let out_filename2 = args.next().unwrap();

    /*
     * set up the connection
     */
    let conn = libpq::Connection::set_db(None, None, None, None, Some(&database))?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    conn.exec("begin");

    println!("importing file \"{in_filename}\" ...");
    let lobj_oid = libpq::lo::import(&conn, &in_filename);

    println!("\tas large object {lobj_oid}.");

    println!("picking out bytes 4294967000-4294968000 of the large object");
    pickout(&conn, lobj_oid, 4_294_967_000, 1_000)?;

    println!("overwriting bytes 4294967000-4294968000 of the large object with X's");
    overwrite(&conn, lobj_oid, 4_294_967_000, 1_000)?;

    println!("exporting large object to file \"{out_filename}\" ...");
    libpq::lo::export(&conn, &out_filename, lobj_oid)?;

    println!("truncating to 3294968000 bytes");
    my_truncate(&conn, lobj_oid, 3_294_968_000)?;

    println!("exporting truncated large object to file \"{out_filename2}\" ...");
    libpq::lo::export(&conn, &out_filename2, lobj_oid)?;

    conn.exec("end");

    Ok(())
}

examples/testlibpq4.rs (line 29)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args();

    if args.len() < 4 {
        panic!(
            "usage: {} table_name db_name1 db_name2\n      compares two tables in two databases",
            args.next().unwrap()
        );
    }

    let _tbl_name = args.nth(1).unwrap();
    let db_name1 = args.next().unwrap();
    let db_name2 = args.next().unwrap();

    /*
     * begin, by setting the parameters for a backend connection if the
     * parameters are None, then the system will try to use reasonable
     * defaults by looking up environment variables or, failing that, using
     * hardwired constants
     */

    /* make a connection to the database */
    let conn1 = libpq::Connection::set_db(None, None, None, None, Some(&db_name1))?;
    check_prepare_conn(&conn1, &db_name1);

    let conn2 = libpq::Connection::set_db(None, None, None, None, Some(&db_name2))?;
    check_prepare_conn(&conn2, &db_name2);

    /* start a transaction block */
    let res1 = conn1.exec("BEGIN");
    if res1.status() != libpq::Status::CommandOk {
        panic!("BEGIN command failed");
    }

    /*
     * fetch instances from the pg_database, the system catalog of databases
     */
    let res1 = conn1.exec("DECLARE myportal CURSOR FOR select * from pg_database");
    if res1.status() != libpq::Status::CommandOk {
        panic!("DECLARE CURSOR command failed");
    }

    let res1 = conn1.exec("FETCH ALL in myportal");
    if res1.status() != libpq::Status::TuplesOk {
        panic!("FETCH ALL command didn't return tuples properly");
    }

    /* first, print out the attribute names */
    let nfields = res1.nfields();
    for i in 0..nfields {
        print!("{:15}", res1.field_name(i)?.unwrap_or_default());
    }
    println!("\n");

    /* next, print out the instances */
    for i in 0..res1.ntuples() {
        for j in 0..nfields {
            let s = res1
                .value(i, j)
                .map(|x| String::from_utf8(x.to_vec()).unwrap())
                .unwrap_or_default();
            print!("{s:15}");
        }
        println!();
    }

    /* close the portal */
    conn1.exec("CLOSE myportal");

    /* end the transaction */
    conn1.exec("END");

    Ok(())
}

pub fn login( host: Option<&str>, port: Option<&str>, options: Option<&str>, tty: Option<&str>, db_name: Option<&str>, login: Option<&str>, pwd: Option<&str>, ) -> Result<Self>

Makes a new connection to the database server.

See PQsetdbLogin.

pub fn poll(&self) -> Status

See PQconnectPoll.

pub fn reset(&self)

Resets the communication channel to the server.

See PQreset.

pub fn reset_start(&self)

Reset the communication channel to the server, in a nonblocking manner.

See PQresetStart.

pub fn reset_poll(&self) -> Status

See PQresetPoll.

pub fn ping_params( params: &HashMap<String, String>, expand_dbname: bool, ) -> Status

Reports the status of the server.

It accepts connection parameters identical to those of libpq::Connection::with_params. It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt.

See PQpingParams.

pub fn ping(dsn: &str) -> Status

Reports the status of the server.

It accepts connection parameters identical to those of libpq::Connection::new. It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt.

See PQping.

pub fn info(&self) -> Result<HashMap<String, Info>>

Return the connection options used for the connection

See PQconninfo.

impl Connection

Control Functions

pub fn client_encoding(&self) -> Encoding

Returns the client encoding.

See PQclientEncoding.

pub fn set_client_encoding(&self, encoding: Encoding)

Sets the client encoding.

See PQsetClientEncoding.

pub fn set_error_verbosity(&self, verbosity: Verbosity) -> Verbosity

Determines the verbosity of messages returned by libpq::Connection::error_message and libpq::Result::error_message.

See PQsetErrorVerbosity.

impl Connection

Functions Associated with the COPY Command

pub fn put_copy_data(&self, buffer: &[u8]) -> Result

Sends data to the server during libpq::Status::CopyIn state.

See PQputCopyData.

pub fn put_copy_end(&self, errormsg: Option<&str>) -> Result

Sends end-of-data indication to the server during libpq::Status::CopyIn state.

See PQputCopyEnd.

pub fn copy_data(&self, async: bool) -> Result<PqBytes>

Receives data from the server during libpq::Status::CopyOut or libpq::Status::CopyBoth state.

On success, this method returns PqBytes.

See PQgetCopyData

impl Connection

Command Execution Functions

pub fn exec(&self, query: &str) -> PQResult

Submits a command to the server and waits for the result.

See PQexec.

Examples found in repository

examples/testlo.rs (line 27)

fn main() -> libpq::errors::Result {
    let mut args = std::env::args();

    if args.len() < 4 {
        panic!(
            "usage: {} database_name in_filename out_filename",
            args.next().unwrap()
        );
    }

    let database = args.nth(1).unwrap();
    let in_filename = args.next().unwrap();
    let out_filename = args.next().unwrap();

    /*
     * set up the connection
     */
    let conn = libpq::Connection::set_db(None, None, None, None, Some(&database))?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    conn.exec("begin");
    println!("importing file \"{in_filename}\" ...");
    let lobj_oid = libpq::lo::import(&conn, &in_filename);

    println!("\tas large object {lobj_oid}.");

    println!("picking out bytes 1000-2000 of the large object");
    pickout(&conn, lobj_oid, 1_000, 1_000)?;

    println!("overwriting bytes 1000-2000 of the large object with X's");
    overwrite(&conn, lobj_oid, 1_000, 1_000)?;

    println!("exporting large object to file \"{out_filename}\" ...");
    libpq::lo::export(&conn, &out_filename, lobj_oid)?;

    conn.exec("end");

    Ok(())
}

examples/testlo64.rs (line 28)

fn main() -> libpq::errors::Result {
    let mut args = std::env::args();

    if args.len() < 5 {
        panic!(
            "usage: {} database_name in_filename out_filename out_filename2",
            args.next().unwrap()
        );
    }

    let database = args.nth(1).unwrap();
    let in_filename = args.next().unwrap();
    let out_filename = args.next().unwrap();
    let out_filename2 = args.next().unwrap();

    /*
     * set up the connection
     */
    let conn = libpq::Connection::set_db(None, None, None, None, Some(&database))?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    conn.exec("begin");

    println!("importing file \"{in_filename}\" ...");
    let lobj_oid = libpq::lo::import(&conn, &in_filename);

    println!("\tas large object {lobj_oid}.");

    println!("picking out bytes 4294967000-4294968000 of the large object");
    pickout(&conn, lobj_oid, 4_294_967_000, 1_000)?;

    println!("overwriting bytes 4294967000-4294968000 of the large object with X's");
    overwrite(&conn, lobj_oid, 4_294_967_000, 1_000)?;

    println!("exporting large object to file \"{out_filename}\" ...");
    libpq::lo::export(&conn, &out_filename, lobj_oid)?;

    println!("truncating to 3294968000 bytes");
    my_truncate(&conn, lobj_oid, 3_294_968_000)?;

    println!("exporting truncated large object to file \"{out_filename2}\" ...");
    libpq::lo::export(&conn, &out_filename2, lobj_oid)?;

    conn.exec("end");

    Ok(())
}

examples/testlibpq2.rs (line 45)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Issue LISTEN command to enable notifications from the rule's NOTIFY.
     */
    let res = conn.exec("LISTEN TBL2");
    if res.status() != libpq::Status::CommandOk {
        panic!("LISTEN command failed: {:?}", conn.error_message());
    }

    /* Quit after four notifies are received. */
    let mut nnotifies = 0;

    let sock = conn.socket()?;

    let mut poll = mio::Poll::new()?;
    let mut events = mio::Events::with_capacity(1);
    poll.registry().register(
        &mut mio::unix::SourceFd(&sock),
        mio::Token(0),
        mio::Interest::READABLE,
    )?;

    while nnotifies < 4 {
        /*
         * Sleep until something happens on the connection.
         */
        poll.poll(&mut events, None)?;

        /* Now check for input */
        conn.consume_input()?;
        while let Some(notify) = conn.notifies() {
            eprintln!(
                "ASYNC NOTIFY of '{}' received from backend PID {}",
                notify.relname()?,
                notify.be_pid()
            );
            nnotifies += 1;
            conn.consume_input()?;
        }
    }

    eprintln!("Done.");

    Ok(())
}

examples/testlibpq4.rs (line 36)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args();

    if args.len() < 4 {
        panic!(
            "usage: {} table_name db_name1 db_name2\n      compares two tables in two databases",
            args.next().unwrap()
        );
    }

    let _tbl_name = args.nth(1).unwrap();
    let db_name1 = args.next().unwrap();
    let db_name2 = args.next().unwrap();

    /*
     * begin, by setting the parameters for a backend connection if the
     * parameters are None, then the system will try to use reasonable
     * defaults by looking up environment variables or, failing that, using
     * hardwired constants
     */

    /* make a connection to the database */
    let conn1 = libpq::Connection::set_db(None, None, None, None, Some(&db_name1))?;
    check_prepare_conn(&conn1, &db_name1);

    let conn2 = libpq::Connection::set_db(None, None, None, None, Some(&db_name2))?;
    check_prepare_conn(&conn2, &db_name2);

    /* start a transaction block */
    let res1 = conn1.exec("BEGIN");
    if res1.status() != libpq::Status::CommandOk {
        panic!("BEGIN command failed");
    }

    /*
     * fetch instances from the pg_database, the system catalog of databases
     */
    let res1 = conn1.exec("DECLARE myportal CURSOR FOR select * from pg_database");
    if res1.status() != libpq::Status::CommandOk {
        panic!("DECLARE CURSOR command failed");
    }

    let res1 = conn1.exec("FETCH ALL in myportal");
    if res1.status() != libpq::Status::TuplesOk {
        panic!("FETCH ALL command didn't return tuples properly");
    }

    /* first, print out the attribute names */
    let nfields = res1.nfields();
    for i in 0..nfields {
        print!("{:15}", res1.field_name(i)?.unwrap_or_default());
    }
    println!("\n");

    /* next, print out the instances */
    for i in 0..res1.ntuples() {
        for j in 0..nfields {
            let s = res1
                .value(i, j)
                .map(|x| String::from_utf8(x.to_vec()).unwrap())
                .unwrap_or_default();
            print!("{s:15}");
        }
        println!();
    }

    /* close the portal */
    conn1.exec("CLOSE myportal");

    /* end the transaction */
    conn1.exec("END");

    Ok(())
}

fn check_prepare_conn(conn: &libpq::Connection, _db_name: &str) {
    if conn.status() != libpq::connection::Status::Ok {
        panic!("{:?}", conn.error_message());
    }

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }
}

examples/testlibpq.rs (line 20)

fn main() -> libpq::errors::Result {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    /* Make a connection to the database */
    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Our test case here involves using a cursor, for which we must be inside
     * a transaction block.  We could do the whole thing with a single
     * PQexec() of "select * from pg_database", but that's too trivial to make
     * a good example.
     */

    /* Start a transaction block */
    let res = conn.exec("BEGIN");
    if res.status() != libpq::Status::CommandOk {
        panic!("BEGIN command failed: {:?}", conn.error_message());
    }

    /*
     * Fetch rows from pg_database, the system catalog of databases
     */
    let res = conn.exec("DECLARE myportal CURSOR FOR select * from pg_database");
    if res.status() != libpq::Status::CommandOk {
        panic!("DECLARE CURSOR failed: {:?}", conn.error_message());
    }

    let res = conn.exec("FETCH ALL in myportal");
    if res.status() != libpq::Status::TuplesOk {
        panic!("FETCH ALL failed: {:?}", conn.error_message());
    }

    /* first, print out the attribute names */
    let nfields = res.nfields();
    for i in 0..nfields {
        print!("{:15}", res.field_name(i)?.unwrap_or_default());
    }
    println!("\n");

    /* next, print out the rows */
    for i in 0..res.ntuples() {
        for j in 0..nfields {
            let s = res
                .value(i, j)
                .map(|x| String::from_utf8(x.to_vec()).unwrap())
                .unwrap_or_default();
            print!("{s:15}");
        }
        println!();
    }

    /* close the portal ... we don't bother to check for errors ... */
    conn.exec("CLOSE myportal");

    /* end the transaction */
    conn.exec("END");

    Ok(())
}

examples/testlibpq3.rs (line 47)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    /* Make a connection to the database */
    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SET search_path = testlibpq3");
    if res.status() != libpq::Status::CommandOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * The point of this program is to illustrate use of PQexecParams() with
     * out-of-line parameters, as well as binary transmission of data.
     *
     * This first example transmits the parameters as text, but receives the
     * results in binary format.  By using out-of-line parameters we can avoid
     * a lot of tedious mucking about with quoting and escaping, even though
     * the data is text.  Notice how we don't have to do anything special with
     * the quote mark in the parameter value.
     */

    /* Here is our out-of-line parameter value */
    let param_values = [Some("joe's place\0".as_bytes())];

    let res = conn.exec_params(
        "SELECT * FROM test1 WHERE t = $1",
        &[], /* let the backend deduce param type */
        param_values.as_slice(),
        &[],                   /* default to all text params */
        libpq::Format::Binary, /* ask for binary results */
    );

    if res.status() != libpq::Status::TuplesOk {
        panic!("SELECT failed: {:?}", conn.error_message());
    }

    show_binary_results(&res)?;

    /*
     * In this second example we transmit an integer parameter in binary form,
     * and again retrieve the results in binary form.
     *
     * Although we tell PQexecParams we are letting the backend deduce
     * parameter type, we really force the decision by casting the parameter
     * symbol in the query text.  This is a good safety measure when sending
     * binary parameters.
     */

    /* Convert integer value "2" to network byte order */
    let binary_int_val = htonl(2);

    /* Set up parameter arrays for PQexecParams */
    let param_values = [Some(binary_int_val.as_slice())];
    let param_formats = vec![libpq::Format::Binary];

    let res = conn.exec_params(
        "SELECT * FROM test1 WHERE i = $1::int4",
        &[], /* let the backend deduce param type */
        &param_values,
        &param_formats,
        libpq::Format::Binary, /* ask for binary results */
    );

    if res.status() != libpq::Status::TuplesOk {
        panic!("SELECT failed: {:?}", conn.error_message());
    }

    show_binary_results(&res)?;

    Ok(())
}

pub fn exec_params( &self, command: &str, param_types: &[Oid], param_values: &[Option<&[u8]>], param_formats: &[Format], result_format: Format, ) -> PQResult

Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.

See PQexecParams.

Examples found in repository

examples/testlibpq3.rs (lines 66-72)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    /* Make a connection to the database */
    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SET search_path = testlibpq3");
    if res.status() != libpq::Status::CommandOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * The point of this program is to illustrate use of PQexecParams() with
     * out-of-line parameters, as well as binary transmission of data.
     *
     * This first example transmits the parameters as text, but receives the
     * results in binary format.  By using out-of-line parameters we can avoid
     * a lot of tedious mucking about with quoting and escaping, even though
     * the data is text.  Notice how we don't have to do anything special with
     * the quote mark in the parameter value.
     */

    /* Here is our out-of-line parameter value */
    let param_values = [Some("joe's place\0".as_bytes())];

    let res = conn.exec_params(
        "SELECT * FROM test1 WHERE t = $1",
        &[], /* let the backend deduce param type */
        param_values.as_slice(),
        &[],                   /* default to all text params */
        libpq::Format::Binary, /* ask for binary results */
    );

    if res.status() != libpq::Status::TuplesOk {
        panic!("SELECT failed: {:?}", conn.error_message());
    }

    show_binary_results(&res)?;

    /*
     * In this second example we transmit an integer parameter in binary form,
     * and again retrieve the results in binary form.
     *
     * Although we tell PQexecParams we are letting the backend deduce
     * parameter type, we really force the decision by casting the parameter
     * symbol in the query text.  This is a good safety measure when sending
     * binary parameters.
     */

    /* Convert integer value "2" to network byte order */
    let binary_int_val = htonl(2);

    /* Set up parameter arrays for PQexecParams */
    let param_values = [Some(binary_int_val.as_slice())];
    let param_formats = vec![libpq::Format::Binary];

    let res = conn.exec_params(
        "SELECT * FROM test1 WHERE i = $1::int4",
        &[], /* let the backend deduce param type */
        &param_values,
        &param_formats,
        libpq::Format::Binary, /* ask for binary results */
    );

    if res.status() != libpq::Status::TuplesOk {
        panic!("SELECT failed: {:?}", conn.error_message());
    }

    show_binary_results(&res)?;

    Ok(())
}

pub fn prepare( &self, name: Option<&str>, query: &str, param_types: &[Oid], ) -> PQResult

Submits a request to create a prepared statement with the given parameters, and waits for completion.

See PQprepare.

pub fn exec_prepared( &self, name: Option<&str>, param_values: &[Option<&[u8]>], param_formats: &[Format], result_format: Format, ) -> PQResult

Sends a request to execute a prepared statement with given parameters, and waits for the result.

See PQexecPrepared.

pub fn describe_prepared(&self, name: Option<&str>) -> PQResult

Submits a request to obtain information about the specified prepared statement, and waits for completion.

See PQdescribePrepared.

pub fn describe_portal(&self, name: Option<&str>) -> PQResult

Submits a request to obtain information about the specified portal, and waits for completion.

See PQdescribePortal.

pub fn escape_literal(&self, str: &str) -> Result<PqString>

Escape a string for use within an SQL command.

On success, this method returns PqString. See PQescapeLiteral.

pub fn escape_identifier(&self, str: &str) -> Result<PqString>

Escapes a string for use as an SQL identifier, such as a table, column, or function name.

On success, this method returns PqString.

See PQescapeIdentifier.

pub fn escape_string(&self, from: &str) -> Result<String>

Escape string literals, much like libpq::Connection::literal.

On success, this method returns String.

See PQescapeStringConn.

pub fn escape_bytea(&self, from: &[u8]) -> Result<PqBytes>

Escapes binary data for use within an SQL command with the type bytea.

On success, this method returns PqBytes.

See PQescapeByteaConn.

impl Connection

pub fn gss_enc_in_use(&self) -> bool

Return true if GSSAPI encryption is in use

pub fn gss_context(&self) -> *const c_void

Returns GSSAPI context if GSSAPI is in use

Safety

This function returns a void* pointer.

impl Connection

Notice Processing

pub unsafe fn set_notice_processor( &self, proc: NoticeProcessor, arg: *mut c_void, ) -> NoticeProcessor

Safety

This function takes a void* pointer as argument.

pub unsafe fn set_notice_receiver( &self, proc: NoticeReceiver, arg: *mut c_void, ) -> NoticeReceiver

Safety

This function takes a void* pointer as argument.

impl Connection

Asynchronous Notification

pub fn notifies(&self) -> Option<Notify>

Returns the next notification from a list of unhandled notification messages received from the server.

Examples found in repository

examples/testlibpq2.rs (line 79)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Issue LISTEN command to enable notifications from the rule's NOTIFY.
     */
    let res = conn.exec("LISTEN TBL2");
    if res.status() != libpq::Status::CommandOk {
        panic!("LISTEN command failed: {:?}", conn.error_message());
    }

    /* Quit after four notifies are received. */
    let mut nnotifies = 0;

    let sock = conn.socket()?;

    let mut poll = mio::Poll::new()?;
    let mut events = mio::Events::with_capacity(1);
    poll.registry().register(
        &mut mio::unix::SourceFd(&sock),
        mio::Token(0),
        mio::Interest::READABLE,
    )?;

    while nnotifies < 4 {
        /*
         * Sleep until something happens on the connection.
         */
        poll.poll(&mut events, None)?;

        /* Now check for input */
        conn.consume_input()?;
        while let Some(notify) = conn.notifies() {
            eprintln!(
                "ASYNC NOTIFY of '{}' received from backend PID {}",
                notify.relname()?,
                notify.be_pid()
            );
            nnotifies += 1;
            conn.consume_input()?;
        }
    }

    eprintln!("Done.");

    Ok(())
}

impl Connection

Retrieving Query Results Row-by-Row

pub fn set_single_row_mode(&self) -> Result

Select single-row mode for the currently-executing query.

See PQsetSingleRowMode.

impl Connection

SSL Support

pub fn init_openssl(do_ssl: bool, do_crypto: bool)

Allows applications to select which security libraries to initialize.

See PQinitOpenSSL.

pub fn init_ssl(do_ssl: bool)

Allows applications to select which security libraries to initialize.

See PQinitSSL.

impl Connection

Connection Status Functions

pub fn db(&self) -> Result<String>

Returns the database name of the connection.

See PQdb.

pub fn user(&self) -> Result<String>

Returns the user name of the connection.

See PQuser.

pub fn pass(&self) -> Result<Option<String>>

Returns the password of the connection.

See PQpass.

pub fn host(&self) -> Result<String>

Returns the server host name of the active connection.

This can be a host name, an IP address, or a directory path if the connection is via Unix socket. (The path case can be distinguished because it will always be an absolute path, beginning with /.)

See PQhost.

pub fn hostaddr(&self) -> Result<String>

Available on crate feature v12 only.

Returns the server IP address of the active connection.

This can be the address that a host name resolved to, or an IP address provided through the hostaddr parameter.

See PQhostaddr.

pub fn port(&self) -> Result<String>

Returns the port of the active connection.

See PQport.

pub fn tty(&self) -> Result<Option<String>>

👎Deprecated: the server no longer pays attention to the TTY setting, but the function remains for backward compatibility.

Returns the debug TTY of the connection.

See PQtty.

pub fn options(&self) -> Result<Option<String>>

Returns the command-line options passed in the connection request.

See PQoptions.

pub fn status(&self) -> Status

Returns the status of the connection.

See PQstatus.

Examples found in repository

examples/testlibpq4.rs (line 83)

fn check_prepare_conn(conn: &libpq::Connection, _db_name: &str) {
    if conn.status() != libpq::connection::Status::Ok {
        panic!("{:?}", conn.error_message());
    }

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }
}

pub fn transaction_status(&self) -> Status

Returns the current in-transaction status of the server.

See PQtransactionStatus.

pub fn parameter_status(&self, param: &str) -> Result<String>

Looks up a current parameter setting of the server.

See PQparameterStatus.

pub fn protocol_version(&self) -> i32

Interrogates the frontend/backend protocol being used.

See PQprotocolVersion.

pub fn server_version(&self) -> i32

Returns an integer representing the server version.

See PQserverVersion.

pub fn error_message(&self) -> Option<&str>

Returns the error message most recently generated by an operation on the connection.

See PQerrorMessage.

Implemenatation Notes:

PQerrorMessage returns a localizable string, which depends on the locale settings and is it not guaranteed to be UTF-8 encoded.

Since rust strings are UTF-8 encoded, if the error message cannot be converted to UTF-8, the returned string will not be the actual error message but “PQerrorMessage internal error: the error message is not UTF-8”. You can get the actual error message, by changing your locale settings an UTF-8 compatible one.

Examples found in repository

examples/testlibpq4.rs (line 84)

fn check_prepare_conn(conn: &libpq::Connection, _db_name: &str) {
    if conn.status() != libpq::connection::Status::Ok {
        panic!("{:?}", conn.error_message());
    }

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }
}

examples/testlo.rs (line 29)

fn main() -> libpq::errors::Result {
    let mut args = std::env::args();

    if args.len() < 4 {
        panic!(
            "usage: {} database_name in_filename out_filename",
            args.next().unwrap()
        );
    }

    let database = args.nth(1).unwrap();
    let in_filename = args.next().unwrap();
    let out_filename = args.next().unwrap();

    /*
     * set up the connection
     */
    let conn = libpq::Connection::set_db(None, None, None, None, Some(&database))?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    conn.exec("begin");
    println!("importing file \"{in_filename}\" ...");
    let lobj_oid = libpq::lo::import(&conn, &in_filename);

    println!("\tas large object {lobj_oid}.");

    println!("picking out bytes 1000-2000 of the large object");
    pickout(&conn, lobj_oid, 1_000, 1_000)?;

    println!("overwriting bytes 1000-2000 of the large object with X's");
    overwrite(&conn, lobj_oid, 1_000, 1_000)?;

    println!("exporting large object to file \"{out_filename}\" ...");
    libpq::lo::export(&conn, &out_filename, lobj_oid)?;

    conn.exec("end");

    Ok(())
}

examples/testlo64.rs (line 30)

fn main() -> libpq::errors::Result {
    let mut args = std::env::args();

    if args.len() < 5 {
        panic!(
            "usage: {} database_name in_filename out_filename out_filename2",
            args.next().unwrap()
        );
    }

    let database = args.nth(1).unwrap();
    let in_filename = args.next().unwrap();
    let out_filename = args.next().unwrap();
    let out_filename2 = args.next().unwrap();

    /*
     * set up the connection
     */
    let conn = libpq::Connection::set_db(None, None, None, None, Some(&database))?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    conn.exec("begin");

    println!("importing file \"{in_filename}\" ...");
    let lobj_oid = libpq::lo::import(&conn, &in_filename);

    println!("\tas large object {lobj_oid}.");

    println!("picking out bytes 4294967000-4294968000 of the large object");
    pickout(&conn, lobj_oid, 4_294_967_000, 1_000)?;

    println!("overwriting bytes 4294967000-4294968000 of the large object with X's");
    overwrite(&conn, lobj_oid, 4_294_967_000, 1_000)?;

    println!("exporting large object to file \"{out_filename}\" ...");
    libpq::lo::export(&conn, &out_filename, lobj_oid)?;

    println!("truncating to 3294968000 bytes");
    my_truncate(&conn, lobj_oid, 3_294_968_000)?;

    println!("exporting truncated large object to file \"{out_filename2}\" ...");
    libpq::lo::export(&conn, &out_filename2, lobj_oid)?;

    conn.exec("end");

    Ok(())
}

fn pickout(
    conn: &libpq::Connection,
    lobj_id: libpq::Oid,
    start: i64,
    len: usize,
) -> libpq::errors::Result {
    let lobj = libpq::lo::open(conn, lobj_id, libpq::lo::Inv::READ)?;

    lobj.lseek64(start, libpq::lo::Seek::Set)?;

    if lobj.tell64()? != start {
        panic!("error in lo_tell64: {:?}", conn.error_message());
    }

    let mut nread = 0;

    while len - nread > 0 {
        let mut buf = lobj.read(len - nread)?;
        let nbytes = buf.len();
        buf.insert(nbytes, '\0');
        eprint!(">>> {buf}");
        nread += nbytes;
        if nbytes == 0 {
            break; /* no more data? */
        }
    }
    eprintln!();

    Ok(())
}

examples/testlibpq2.rs (line 47)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Issue LISTEN command to enable notifications from the rule's NOTIFY.
     */
    let res = conn.exec("LISTEN TBL2");
    if res.status() != libpq::Status::CommandOk {
        panic!("LISTEN command failed: {:?}", conn.error_message());
    }

    /* Quit after four notifies are received. */
    let mut nnotifies = 0;

    let sock = conn.socket()?;

    let mut poll = mio::Poll::new()?;
    let mut events = mio::Events::with_capacity(1);
    poll.registry().register(
        &mut mio::unix::SourceFd(&sock),
        mio::Token(0),
        mio::Interest::READABLE,
    )?;

    while nnotifies < 4 {
        /*
         * Sleep until something happens on the connection.
         */
        poll.poll(&mut events, None)?;

        /* Now check for input */
        conn.consume_input()?;
        while let Some(notify) = conn.notifies() {
            eprintln!(
                "ASYNC NOTIFY of '{}' received from backend PID {}",
                notify.relname()?,
                notify.be_pid()
            );
            nnotifies += 1;
            conn.consume_input()?;
        }
    }

    eprintln!("Done.");

    Ok(())
}

examples/testlibpq.rs (line 22)

fn main() -> libpq::errors::Result {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    /* Make a connection to the database */
    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Our test case here involves using a cursor, for which we must be inside
     * a transaction block.  We could do the whole thing with a single
     * PQexec() of "select * from pg_database", but that's too trivial to make
     * a good example.
     */

    /* Start a transaction block */
    let res = conn.exec("BEGIN");
    if res.status() != libpq::Status::CommandOk {
        panic!("BEGIN command failed: {:?}", conn.error_message());
    }

    /*
     * Fetch rows from pg_database, the system catalog of databases
     */
    let res = conn.exec("DECLARE myportal CURSOR FOR select * from pg_database");
    if res.status() != libpq::Status::CommandOk {
        panic!("DECLARE CURSOR failed: {:?}", conn.error_message());
    }

    let res = conn.exec("FETCH ALL in myportal");
    if res.status() != libpq::Status::TuplesOk {
        panic!("FETCH ALL failed: {:?}", conn.error_message());
    }

    /* first, print out the attribute names */
    let nfields = res.nfields();
    for i in 0..nfields {
        print!("{:15}", res.field_name(i)?.unwrap_or_default());
    }
    println!("\n");

    /* next, print out the rows */
    for i in 0..res.ntuples() {
        for j in 0..nfields {
            let s = res
                .value(i, j)
                .map(|x| String::from_utf8(x.to_vec()).unwrap())
                .unwrap_or_default();
            print!("{s:15}");
        }
        println!();
    }

    /* close the portal ... we don't bother to check for errors ... */
    conn.exec("CLOSE myportal");

    /* end the transaction */
    conn.exec("END");

    Ok(())
}

examples/testlibpq3.rs (line 49)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    /* Make a connection to the database */
    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SET search_path = testlibpq3");
    if res.status() != libpq::Status::CommandOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * The point of this program is to illustrate use of PQexecParams() with
     * out-of-line parameters, as well as binary transmission of data.
     *
     * This first example transmits the parameters as text, but receives the
     * results in binary format.  By using out-of-line parameters we can avoid
     * a lot of tedious mucking about with quoting and escaping, even though
     * the data is text.  Notice how we don't have to do anything special with
     * the quote mark in the parameter value.
     */

    /* Here is our out-of-line parameter value */
    let param_values = [Some("joe's place\0".as_bytes())];

    let res = conn.exec_params(
        "SELECT * FROM test1 WHERE t = $1",
        &[], /* let the backend deduce param type */
        param_values.as_slice(),
        &[],                   /* default to all text params */
        libpq::Format::Binary, /* ask for binary results */
    );

    if res.status() != libpq::Status::TuplesOk {
        panic!("SELECT failed: {:?}", conn.error_message());
    }

    show_binary_results(&res)?;

    /*
     * In this second example we transmit an integer parameter in binary form,
     * and again retrieve the results in binary form.
     *
     * Although we tell PQexecParams we are letting the backend deduce
     * parameter type, we really force the decision by casting the parameter
     * symbol in the query text.  This is a good safety measure when sending
     * binary parameters.
     */

    /* Convert integer value "2" to network byte order */
    let binary_int_val = htonl(2);

    /* Set up parameter arrays for PQexecParams */
    let param_values = [Some(binary_int_val.as_slice())];
    let param_formats = vec![libpq::Format::Binary];

    let res = conn.exec_params(
        "SELECT * FROM test1 WHERE i = $1::int4",
        &[], /* let the backend deduce param type */
        &param_values,
        &param_formats,
        libpq::Format::Binary, /* ask for binary results */
    );

    if res.status() != libpq::Status::TuplesOk {
        panic!("SELECT failed: {:?}", conn.error_message());
    }

    show_binary_results(&res)?;

    Ok(())
}

pub fn socket(&self) -> Result<i32>

Obtains the file descriptor number of the connection socket to the server.

See PQsocket.

Examples found in repository

examples/testlibpq2.rs (line 61)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    let conninfo = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "dbname = postgres".to_string());

    let conn = libpq::Connection::new(&conninfo)?;

    /* Set always-secure search path, so malicious users can't take control. */
    let res = conn.exec("SELECT pg_catalog.set_config('search_path', '', false)");
    if res.status() != libpq::Status::TuplesOk {
        panic!("SET failed: {:?}", conn.error_message());
    }

    /*
     * Issue LISTEN command to enable notifications from the rule's NOTIFY.
     */
    let res = conn.exec("LISTEN TBL2");
    if res.status() != libpq::Status::CommandOk {
        panic!("LISTEN command failed: {:?}", conn.error_message());
    }

    /* Quit after four notifies are received. */
    let mut nnotifies = 0;

    let sock = conn.socket()?;

    let mut poll = mio::Poll::new()?;
    let mut events = mio::Events::with_capacity(1);
    poll.registry().register(
        &mut mio::unix::SourceFd(&sock),
        mio::Token(0),
        mio::Interest::READABLE,
    )?;

    while nnotifies < 4 {
        /*
         * Sleep until something happens on the connection.
         */
        poll.poll(&mut events, None)?;

        /* Now check for input */
        conn.consume_input()?;
        while let Some(notify) = conn.notifies() {
            eprintln!(
                "ASYNC NOTIFY of '{}' received from backend PID {}",
                notify.relname()?,
                notify.be_pid()
            );
            nnotifies += 1;
            conn.consume_input()?;
        }
    }

    eprintln!("Done.");

    Ok(())
}

pub fn backend_pid(&self) -> u32

Returns the process ID (PID) of the backend process handling this connection.

See PQbackendPID.

pub fn needs_password(&self) -> bool

Returns true if the connection authentication method required a password, but none was available. Returns false if not.

See PQconnectionNeedsPassword.

pub fn used_password(&self) -> bool

Returns true if the connection authentication method used a password. Returns false if not.

See PQconnectionUsedPassword.

pub fn ssl_in_use(&self) -> bool

Returns true if the connection uses SSL, false if not.

See PQsslInUse.

pub fn ssl_attribute(&self, attribute: Attribute) -> Result<Option<String>>

Returns SSL-related information about the connection.

See PQsslAttribute.

pub fn ssl_attribute_names(&self) -> Result<Vec<Attribute>>

Return an array of SSL attribute names available.

See PQsslAttributeNames.

pub unsafe fn ssl_struct(&self, struct_name: &str) -> *const c_void

Return a pointer to an SSL-implementation-specific object describing the connection.

See PQsslStruct.

Safety

This function returns a void* pointer.

pub unsafe fn ssl(&self) -> *const c_void

Returns the SSL structure used in the connection, or null if SSL is not in use.

See PQgetssl.

Safety

This function returns a void* pointer.

impl Connection

Behavior in Threaded Programs

pub fn is_thread_safe() -> bool

Returns the thread safety status of the libpq library.

See PQisthreadsafe.

impl Connection

pub fn trace(&self, file: File)

Available on Unix only.

Enables tracing of the client/server communication to a debugging file stream.

See PQtrace.

pub fn untrace(&self)

Available on Unix only.

Disables tracing started by libpq::Connection::trace.

See PQuntrace.

pub fn trace_set_flags(&self, flags: Flags)

Available on crate feature v14 only.

Controls the tracing behavior of client/server communication.

impl Connection

pub fn encrypt_password( &self, passwd: &str, user: &str, algorithm: Option<&str>, ) -> Result<PqString>

Prepares the encrypted form of a PostgreSQL password.

On success, this method returns PqString.

See PQencryptPasswordConn.

pub fn send_flush_request(&self) -> Result

Available on crate feature v14 only.

Alias for pipeline::flush_request.

Trait Implementations

impl Clone for Connection

fn clone(&self) -> Connection

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Connection

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

Formats the value using the given formatter.

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Connection