Struct libpq::connection::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<Vec<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<Vec<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<Result>

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.

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.

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.

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) -> Result

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

See PQexec.

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

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.

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

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<Vec<u8>>], param_formats: &[Format], result_format: Format ) -> Result

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>) -> Result

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>) -> Result

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

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.

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 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.

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.

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

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

See PQsocket.

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)

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

See PQtrace.

pub fn untrace(&self)

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

See PQuntrace.

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.

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