Struct Opts

pub struct Opts { /* private fields */ }

Mysql connection options.

Build one with OptsBuilder.

Implementations

impl Opts

pub fn from_url(url: &str) -> Result<Opts, UrlError>

pub fn ip_or_hostname(&self) -> &str

Address of mysql server (defaults to 127.0.0.1). Hostnames should also work.

pub fn tcp_port(&self) -> u16

TCP port of mysql server (defaults to 3306).

pub fn resolved_ips(&self) -> &Option<Vec<IpAddr>>

The resolved IPs for the mysql server, if provided.

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

User (defaults to None).

Connection URL

Can be defined in connection URL. E.g.

let opts = Opts::from_url("mysql://user@localhost/database_name")?;
assert_eq!(opts.user(), Some("user"));

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

Password (defaults to None).

Connection URL

Can be defined in connection URL. E.g.

let opts = Opts::from_url("mysql://user:pass%20word@localhost/database_name")?;
assert_eq!(opts.pass(), Some("pass word"));

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

Database name (defaults to None).

Connection URL

Database name can be defined in connection URL. E.g.

let opts = Opts::from_url("mysql://localhost/database_name")?;
assert_eq!(opts.db_name(), Some("database_name"));

pub fn init(&self) -> &[String]

Commands to execute once new connection is established.

pub fn setup(&self) -> &[String]

Commands to execute on new connection and every time Conn::reset or Conn::change_user is invoked.

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

TCP keep alive timeout in milliseconds (defaults to None).

Connection URL

You can use tcp_keepalive URL parameter to set this value (in milliseconds). E.g.

let opts = Opts::from_url("mysql://localhost/db?tcp_keepalive=10000")?;
assert_eq!(opts.tcp_keepalive(), Some(10_000));

pub fn tcp_nodelay(&self) -> bool

Set the TCP_NODELAY option for the mysql connection (defaults to true).

Setting this option to false re-enables Nagle’s algorithm, which can cause unusually high latency (~40ms) but may increase maximum throughput. See #132.

Connection URL

You can use tcp_nodelay URL parameter to set this value. E.g.

let opts = Opts::from_url("mysql://localhost/db?tcp_nodelay=false")?;
assert_eq!(opts.tcp_nodelay(), false);

pub fn local_infile_handler(&self) -> Option<Arc<dyn GlobalHandler>>

Handler for local infile requests (defaults to None).

pub fn pool_opts(&self) -> &PoolOpts

Connection pool options (defaults to Default::default).

pub fn conn_ttl(&self) -> Option<Duration>

Pool will close connection if time since last IO exceeds this number of seconds (defaults to wait_timeout. None to reset to default).

Connection URL

You can use conn_ttl URL parameter to set this value (in seconds). E.g.

let opts = Opts::from_url("mysql://localhost/db?conn_ttl=360")?;
assert_eq!(opts.conn_ttl(), Some(Duration::from_secs(360)));

pub fn abs_conn_ttl(&self) -> Option<Duration>

The pool will close a connection when this absolute TTL has elapsed. Disabled by default.

Enables forced recycling and migration of connections in a guaranteed timeframe. This TTL bypasses pool constraints and an idle pool can go below the min size.

Connection URL

You can use abs_conn_ttl URL parameter to set this value (in seconds). E.g.

let opts = Opts::from_url("mysql://localhost/db?abs_conn_ttl=86400")?;
assert_eq!(opts.abs_conn_ttl(), Some(Duration::from_secs(24 * 60 * 60)));

pub fn abs_conn_ttl_jitter(&self) -> Option<Duration>

Upper bound of a random value added to the absolute TTL, if enabled. Disabled by default.

Should be used to prevent connections from closing at the same time.

Connection URL

You can use abs_conn_ttl_jitter URL parameter to set this value (in seconds). E.g.

let opts = Opts::from_url("mysql://localhost/db?abs_conn_ttl=7200&abs_conn_ttl_jitter=3600")?;
assert_eq!(opts.abs_conn_ttl_jitter(), Some(Duration::from_secs(60 * 60)));

pub fn stmt_cache_size(&self) -> usize

Number of prepared statements cached on the client side (per connection). Defaults to DEFAULT_STMT_CACHE_SIZE.

Call with None to reset to default. Set to 0 to disable statement cache.

Caveats

If statement cache is disabled (stmt_cache_size is 0), then you must close statements manually.

Connection URL

You can use stmt_cache_size URL parameter to set this value. E.g.

let opts = Opts::from_url("mysql://localhost/db?stmt_cache_size=128")?;
assert_eq!(opts.stmt_cache_size(), 128);

pub fn ssl_opts(&self) -> Option<&SslOpts>

Driver will require SSL connection if this opts isn’t None (defaults to None).

Connection URL parameters

Note that for securty reasons:

• CA and IDENTITY verifications are opt-out
• there is no way to give an idenity or root certs via query URL

URL Parameters:

• require_ssl: bool (defaults to false) – requires SSL with default SslOpts
• verify_ca: bool (defaults to true) – requires server Certificate Authority (CA) certificate validation against the configured CA certificates. Makes no sence if require_ssl equals false.
• verify_identity: bool (defaults to true) – perform host name identity verification by checking the host name the client uses for connecting to the server against the identity in the certificate that the server sends to the client. Makes no sence if require_ssl equals false.

pub fn prefer_socket(&self) -> bool

Prefer socket connection (defaults to true temporary false on Windows platform).

Will reconnect via socket (or named pipe on Windows) after TCP connection to 127.0.0.1 if true.

Will fall back to TCP on error. Use socket option to enforce socket connection.

Note

Library will query the @@socket server variable to get socket address, and this address may be incorrect in some cases (e.g. docker).

Connection URL

You can use prefer_socket URL parameter to set this value. E.g.

let opts = Opts::from_url("mysql://localhost/db?prefer_socket=false")?;
assert_eq!(opts.prefer_socket(), false);

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

Path to unix socket (or named pipe on Windows) (defaults to None).

Connection URL

You can use socket URL parameter to set this value. E.g.

let opts = Opts::from_url("mysql://localhost/db?socket=%2Fpath%2Fto%2Fsocket")?;
assert_eq!(opts.socket(), Some("/path/to/socket"));

pub fn compression(&self) -> Option<Compression>

If not None, then client will ask for compression if server supports it (defaults to None).

Connection URL

You can use compression URL parameter to set this value:

• fast - for compression level 1;
• best - for compression level 9;
• on, true - for default compression level;
• 0, …, 9.

Note that compression level defined here will affect only outgoing packets.

pub fn max_allowed_packet(&self) -> Option<usize>

Client side max_allowed_packet value (defaults to None).

By default Conn will query this value from the server. One can avoid this step by explicitly specifying it. Server side default is 4MB.

Available in connection URL via max_allowed_packet parameter.

pub fn wait_timeout(&self) -> Option<usize>

Client side wait_timeout value (defaults to None).

By default Conn will query this value from the server. One can avoid this step by explicitly specifying it. Server side default is 28800.

Available in connection URL via wait_timeout parameter.

pub fn secure_auth(&self) -> bool

Disables mysql_old_password plugin (defaults to true).

Available via secure_auth connection url parameter.

pub fn client_found_rows(&self) -> bool

Returns true if CLIENT_FOUND_ROWS capability is enabled (defaults to false).

CLIENT_FOUND_ROWS changes the behavior of the affected count returned for writes (UPDATE/INSERT etc). It makes MySQL return the FOUND rows instead of the AFFECTED rows.

Connection URL

Use client_found_rows URL parameter to set this value. E.g.

let opts = Opts::from_url("mysql://localhost/db?client_found_rows=true")?;
assert!(opts.client_found_rows());

pub fn enable_cleartext_plugin(&self) -> bool

Returns true if mysql_clear_password plugin support is enabled (defaults to false).

mysql_clear_password enables client to send passwords to the server as cleartext, without hashing or encryption (consult MySql documentation for more info).

Security Notes

Sending passwords as cleartext may be a security problem in some configurations. Please consider using TLS or encrypted tunnels for server connection.

Connection URL

Use enable_cleartext_plugin URL parameter to set this value. E.g.

let opts = Opts::from_url("mysql://localhost/db?enable_cleartext_plugin=true")?;
assert!(opts.enable_cleartext_plugin());

Trait Implementations

impl Clone for Opts

fn clone(&self) -> Opts

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Opts

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

Formats the value using the given formatter.

impl Default for Opts

fn default() -> Opts

Returns the “default value” for a type.

impl From<OptsBuilder> for Opts

fn from(builder: OptsBuilder) -> Opts

Converts to this type from the input type.

impl FromStr for Opts

type Err = UrlError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err>

Parses a string s to return a value of this type.

impl PartialEq for Opts

fn eq(&self, other: &Opts) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<&str> for Opts

type Error = UrlError

The type returned in the event of a conversion error.

fn try_from(s: &str) -> Result<Self, UrlError>

Performs the conversion.

impl Eq for Opts

impl StructuralPartialEq for Opts