Struct Connection

pub struct Connection<'c> { /* private fields */ }

The connection handle references storage of all information about the connection to the data source, including status, transaction state, and error information.

Connection is not Sync, this implies that many methods which one would suspect should take &mut self are actually &self. This is important if several statement exists which borrow the same connection.

Implementations

impl<'c> Connection<'c>

pub unsafe fn new(handle: HDbc) -> Self

Safety

Call this method only with a valid (successfully allocated) ODBC connection handle.

pub fn as_sys(&self) -> HDbc

Directly acces the underlying ODBC handle.

pub fn connect( &mut self, data_source_name: &SqlText<'_>, user: &SqlText<'_>, pwd: &SqlText<'_>, ) -> SqlResult<()>

Establishes connections to a driver and a data source.

• See Connecting with SQLConnect
• See SQLConnectFunction

Arguments

• data_source_name - Data source name. The data might be located on the same computer as the program, or on another computer somewhere on a network.
• user - User identifier.
• pwd - Authentication string (typically the password).

pub fn connect_with_connection_string( &mut self, connection_string: &SqlText<'_>, ) -> SqlResult<()>

An alternative to connect. It supports data sources that require more connection information than the three arguments in connect and data sources that are not defined in the system information.

pub unsafe fn driver_connect( &mut self, connection_string: &SqlText<'_>, parent_window: HWnd, completed_connection_string: &mut OutputStringBuffer, driver_completion: DriverConnectOption, ) -> SqlResult<()>

An alternative to connect for connecting with a connection string. Allows for completing a connection string with a GUI prompt on windows.

Return

SqlResult::NoData in case the prompt completing the connection string has been aborted.

Safety

parent_window must either be a valid window handle or NULL.

pub fn disconnect(&mut self) -> SqlResult<()>

Disconnect from an ODBC data source.

pub fn allocate_statement(&self) -> SqlResult<StatementImpl<'_>>

Allocate a new statement handle. The Statement must not outlive the Connection.

pub fn set_autocommit(&self, enabled: bool) -> SqlResult<()>

Specify the transaction mode. By default, ODBC transactions are in auto-commit mode (unless SQLSetConnectAttr and SQLSetConnectOption are not supported, which is unlikely). Switching from manual-commit mode to auto-commit mode automatically commits any open transaction on the connection.

pub fn set_login_timeout_sec(&self, timeout: u32) -> SqlResult<()>

Number of seconds to wait for a login request to complete before returning to the application. The default is driver-dependent. If 0 the timeout is dasabled and a connection attempt will wait indefinitely.

If the specified timeout exceeds the maximum login timeout in the data source, the driver substitutes that value and uses the maximum login timeout instead.

This corresponds to the SQL_ATTR_LOGIN_TIMEOUT attribute in the ODBC specification.

See: https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlsetconnectattr-function

pub fn set_packet_size(&self, packet_size: u32) -> SqlResult<()>

Specifying the network packet size in bytes. Note: Many data sources either do not support this option or only can return but not set the network packet size. If the specified size exceeds the maximum packet size or is smaller than the minimum packet size, the driver substitutes that value and returns SQLSTATE 01S02 (Option value changed). If the application sets packet size after a connection has already been made, the driver will return SQLSTATE HY011 (Attribute cannot be set now).

See: https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlsetconnectattr-function

pub fn commit(&self) -> SqlResult<()>

To commit a transaction in manual-commit mode.

pub fn rollback(&self) -> SqlResult<()>

Roll back a transaction in manual-commit mode.

pub fn fetch_database_management_system_name( &self, buf: &mut Vec<SqlChar>, ) -> SqlResult<()>

Fetch the name of the database management system used by the connection and store it into the provided buf.

pub fn max_catalog_name_len(&self) -> SqlResult<u16>

Maximum length of catalog names.

pub fn max_schema_name_len(&self) -> SqlResult<u16>

Maximum length of schema names.

pub fn max_table_name_len(&self) -> SqlResult<u16>

Maximum length of table names.

pub fn max_column_name_len(&self) -> SqlResult<u16>

Maximum length of column names.

pub fn fetch_current_catalog(&self, buffer: &mut Vec<SqlChar>) -> SqlResult<()>

Fetch the name of the current catalog being used by the connection and store it into the provided buf.

pub fn is_dead(&self) -> SqlResult<bool>

Indicates the state of the connection. If true the connection has been lost. If false, the connection is still active.

pub fn packet_size(&self) -> SqlResult<u32>

Networ packet size in bytes.

Trait Implementations

impl<'c> AsHandle for Connection<'c>

fn as_handle(&self) -> Handle

The raw underlying ODBC handle used to talk to the ODBC C API. The handle must be valid.

fn handle_type(&self) -> HandleType

The type of the ODBC handle returned by as_handle. This is a method rather than a constant in order to make the type object safe.

impl<'c> Drop for Connection<'c>

fn drop(&mut self)

Executes the destructor for this type.

impl<'c> Send for Connection<'c>

According to the ODBC documentation this is safe. See: https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/multithreading

In addition to that, this has not caused trouble in a while. So we mark sending connections to other threads as safe. Reading through the documentation, one might get the impression that Connections are also Sync. This could be theoretically true on the level of the handle, but at the latest once the interior mutability due to error handling comes in to play, higher level abstraction have to content themselves with Send. This is currently how far my trust with most ODBC drivers.