Struct sqlx::mysql::MySqlConnectOptions

source ยท
pub struct MySqlConnectOptions { /* private fields */ }
Available on crate feature mysql only.
Expand description

Options and flags which can be used to configure a MySQL connection.

A value of MySqlConnectOptions can be parsed from a connection URL, as described by MySQL.

The generic format of the connection URL:

mysql://[host][/database][?properties]

This type also implements FromStr so you can parse it from a string containing a connection URL and then further adjust options if necessary (see example below).

ยงProperties

ParameterDefaultDescription
ssl-modePREFERREDDetermines whether or with what priority a secure SSL TCP/IP connection will be negotiated. See MySqlSslMode.
ssl-caNoneSets the name of a file containing a list of trusted SSL Certificate Authorities.
statement-cache-capacity100The maximum number of prepared statements stored in the cache. Set to 0 to disable.
socketNonePath to the unix domain socket, which will be used instead of TCP if set.

ยงExample

use sqlx::{Connection, ConnectOptions};
use sqlx::mysql::{MySqlConnectOptions, MySqlConnection, MySqlPool, MySqlSslMode};

// URL connection string
let conn = MySqlConnection::connect("mysql://root:password@localhost/db").await?;

// Manually-constructed options
let conn = MySqlConnectOptions::new()
    .host("localhost")
    .username("root")
    .password("password")
    .database("db")
    .connect().await?;

// Modifying options parsed from a string
let mut opts: MySqlConnectOptions = "mysql://root:password@localhost/db".parse()?;

// Change the log verbosity level for queries.
// Information about SQL queries is logged at `DEBUG` level by default.
opts.log_statements(log::LevelFilter::Trace);

let pool = MySqlPool::connect_with(&opts).await?;

Implementationsยง

sourceยง

impl MySqlConnectOptions

source

pub fn new() -> MySqlConnectOptions

Creates a new, default set of options ready for configuration

source

pub fn host(self, host: &str) -> MySqlConnectOptions

Sets the name of the host to connect to.

The default behavior when the host is not specified, is to connect to localhost.

source

pub fn port(self, port: u16) -> MySqlConnectOptions

Sets the port to connect to at the server host.

The default port for MySQL is 3306.

source

pub fn socket(self, path: impl AsRef<Path>) -> MySqlConnectOptions

Pass a path to a Unix socket. This changes the connection stream from TCP to UDS.

By default set to None.

source

pub fn username(self, username: &str) -> MySqlConnectOptions

Sets the username to connect as.

source

pub fn password(self, password: &str) -> MySqlConnectOptions

Sets the password to connect with.

source

pub fn database(self, database: &str) -> MySqlConnectOptions

Sets the database name.

source

pub fn ssl_mode(self, mode: MySqlSslMode) -> MySqlConnectOptions

Sets whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.

By default, the SSL mode is Preferred, and the client will first attempt an SSL connection but fallback to a non-SSL connection on failure.

ยงExample
let options = MySqlConnectOptions::new()
    .ssl_mode(MySqlSslMode::Required);
source

pub fn ssl_ca(self, file_name: impl AsRef<Path>) -> MySqlConnectOptions

Sets the name of a file containing a list of trusted SSL Certificate Authorities.

ยงExample
let options = MySqlConnectOptions::new()
    .ssl_mode(MySqlSslMode::VerifyCa)
    .ssl_ca("path/to/ca.crt");
source

pub fn ssl_ca_from_pem(self, pem_certificate: Vec<u8>) -> MySqlConnectOptions

Sets PEM encoded list of trusted SSL Certificate Authorities.

ยงExample
let options = MySqlConnectOptions::new()
    .ssl_mode(MySqlSslMode::VerifyCa)
    .ssl_ca_from_pem(vec![]);
source

pub fn ssl_client_cert(self, cert: impl AsRef<Path>) -> MySqlConnectOptions

Sets the name of a file containing SSL client certificate.

ยงExample
let options = MySqlConnectOptions::new()
    .ssl_mode(MySqlSslMode::VerifyCa)
    .ssl_client_cert("path/to/client.crt");
source

pub fn ssl_client_cert_from_pem( self, cert: impl AsRef<[u8]> ) -> MySqlConnectOptions

Sets the SSL client certificate as a PEM-encoded byte slice.

This should be an ASCII-encoded blob that starts with -----BEGIN CERTIFICATE-----.

ยงExample

Note: embedding SSL certificates and keys in the binary is not advised. This is for illustration purposes only.


const CERT: &[u8] = b"\
-----BEGIN CERTIFICATE-----
<Certificate data here.>
-----END CERTIFICATE-----";

let options = MySqlConnectOptions::new()
    .ssl_mode(MySqlSslMode::VerifyCa)
    .ssl_client_cert_from_pem(CERT);
source

pub fn ssl_client_key(self, key: impl AsRef<Path>) -> MySqlConnectOptions

Sets the name of a file containing SSL client key.

ยงExample
let options = MySqlConnectOptions::new()
    .ssl_mode(MySqlSslMode::VerifyCa)
    .ssl_client_key("path/to/client.key");
source

pub fn ssl_client_key_from_pem( self, key: impl AsRef<[u8]> ) -> MySqlConnectOptions

Sets the SSL client key as a PEM-encoded byte slice.

This should be an ASCII-encoded blob that starts with -----BEGIN PRIVATE KEY-----.

ยงExample

Note: embedding SSL certificates and keys in the binary is not advised. This is for illustration purposes only.


const KEY: &[u8] = b"\
-----BEGIN PRIVATE KEY-----
<Private key data here.>
-----END PRIVATE KEY-----";

let options = MySqlConnectOptions::new()
    .ssl_mode(MySqlSslMode::VerifyCa)
    .ssl_client_key_from_pem(KEY);
source

pub fn statement_cache_capacity(self, capacity: usize) -> MySqlConnectOptions

Sets the capacity of the connectionโ€™s statement cache in a number of stored distinct statements. Caching is handled using LRU, meaning when the amount of queries hits the defined limit, the oldest statement will get dropped.

The default cache capacity is 100 statements.

source

pub fn charset(self, charset: &str) -> MySqlConnectOptions

Sets the character set for the connection.

The default character set is utf8mb4. This is supported from MySQL 5.5.3. If you need to connect to an older version, we recommend you to change this to utf8.

source

pub fn collation(self, collation: &str) -> MySqlConnectOptions

Sets the collation for the connection.

The default collation is derived from the charset. Normally, you should only have to set the charset.

source

pub fn pipes_as_concat(self, flag_val: bool) -> MySqlConnectOptions

Sets the flag that enables or disables the PIPES_AS_CONCAT connection setting

The default value is set to true, but some MySql databases such as PlanetScale error out with this connection setting so it needs to be set false in such cases.

source

pub fn enable_cleartext_plugin(self, flag_val: bool) -> MySqlConnectOptions

Enables mysql_clear_password plugin support.

Security Note: Sending passwords as cleartext may be a security problem in some configurations. Without additional defensive configuration like ssl-mode=VERIFY_IDENTITY, an attacker can compromise a router and trick the application into divulging its credentials.

It is strongly recommended to set .ssl_mode to Required, VerifyCa, or VerifyIdentity when enabling cleartext plugin.

source

pub fn no_engine_subsitution(self, flag_val: bool) -> MySqlConnectOptions

Flag that enables or disables the NO_ENGINE_SUBSTITUTION sql_mode setting after connection.

If not set, if the available storage engine specified by a CREATE TABLE is not available, a warning is given and the default storage engine is used instead.

By default, this is true (NO_ENGINE_SUBSTITUTION is passed, forbidding engine substitution).

https://mariadb.com/kb/en/sql-mode/

source

pub fn timezone(self, value: impl Into<Option<String>>) -> MySqlConnectOptions

If Some, sets the time_zone option to the given string after connecting to the database.

If None, no time_zone parameter is sent; the server timezone will be used instead.

Defaults to Some(String::from("+00:00")) to ensure all timestamps are in UTC.

ยงWarning

Changing this setting from its default will apply an unexpected skew to any time::OffsetDateTime or chrono::DateTime<Utc> value, whether passed as a parameter or decoded as a result. TIMESTAMP values are not encoded with their UTC offset in the MySQL protocol, so encoding and decoding of these types assumes the server timezone is always UTC.

If you are changing this option, ensure your application only uses time::PrimitiveDateTime or chrono::NaiveDateTime and that it does not assume these timestamps can be placed on a real timeline without applying the proper offset.

source

pub fn set_names(self, flag_val: bool) -> MySqlConnectOptions

If enabled, SET NAMES '{charset}' COLLATE '{collation}' is passed with the values of [.charset()] and [.collation()] after connecting to the database.

This ensures the connection uses the specified character set and collation.

Enabled by default.

ยงWarning

If this is disabled and the default charset is not binary-compatible with UTF-8, query strings, column names and string values will likely not decode (or encode) correctly, which may result in unexpected errors or garbage outputs at runtime.

For proper functioning, you must ensure the server is using a binary-compatible charset, such as ASCII or Latin-1 (ISO 8859-1), and that you do not pass any strings containing codepoints not supported by said charset.

Instead of disabling this, you may also consider setting [.charset()] to a charset that is supported by your MySQL or MariaDB server version and compatible with UTF-8.

sourceยง

impl MySqlConnectOptions

source

pub fn get_host(&self) -> &str

Get the current host.

ยงExample
let options = MySqlConnectOptions::new()
    .host("127.0.0.1");
assert_eq!(options.get_host(), "127.0.0.1");
source

pub fn get_port(&self) -> u16

Get the serverโ€™s port.

ยงExample
let options = MySqlConnectOptions::new()
    .port(6543);
assert_eq!(options.get_port(), 6543);
source

pub fn get_socket(&self) -> Option<&PathBuf>

Get the socket path.

ยงExample
let options = MySqlConnectOptions::new()
    .socket("/tmp");
assert!(options.get_socket().is_some());
source

pub fn get_username(&self) -> &str

Get the serverโ€™s port.

ยงExample
let options = MySqlConnectOptions::new()
    .username("foo");
assert_eq!(options.get_username(), "foo");
source

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

Get the current database name.

ยงExample
let options = MySqlConnectOptions::new()
    .database("postgres");
assert!(options.get_database().is_some());
source

pub fn get_ssl_mode(&self) -> MySqlSslMode

Get the SSL mode.

ยงExample
let options = MySqlConnectOptions::new();
assert!(matches!(options.get_ssl_mode(), MySqlSslMode::Preferred));
source

pub fn get_charset(&self) -> &str

Get the server charset.

ยงExample
let options = MySqlConnectOptions::new();
assert_eq!(options.get_charset(), "utf8mb4");
source

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

Get the server collation.

ยงExample
let options = MySqlConnectOptions::new()
    .collation("collation");
assert!(options.get_collation().is_some());

Trait Implementationsยง

sourceยง

impl Clone for MySqlConnectOptions

sourceยง

fn clone(&self) -> MySqlConnectOptions

Returns a copy of the value. Read more
1.0.0 ยท sourceยง

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

Performs copy-assignment from source. Read more
sourceยง

impl ConnectOptions for MySqlConnectOptions

ยง

type Connection = MySqlConnection

sourceยง

fn from_url(url: &Url) -> Result<MySqlConnectOptions, Error>

Parse the ConnectOptions from a URL.
sourceยง

fn to_url_lossy(&self) -> Url

Get a connection URL that may be used to connect to the same database as this ConnectOptions. Read more
sourceยง

fn connect( &self ) -> Pin<Box<dyn Future<Output = Result<<MySqlConnectOptions as ConnectOptions>::Connection, Error>> + Send + '_>>

Establish a new database connection with the options specified by self.
sourceยง

fn log_statements(self, level: LevelFilter) -> MySqlConnectOptions

Log executed statements with the specified level
sourceยง

fn log_slow_statements( self, level: LevelFilter, duration: Duration ) -> MySqlConnectOptions

Log executed statements with a duration above the specified duration at the specified level.
sourceยง

fn disable_statement_logging(self) -> Self

Entirely disables statement logging (both slow and regular).
sourceยง

impl Debug for MySqlConnectOptions

sourceยง

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

Formats the value using the given formatter. Read more
sourceยง

impl Default for MySqlConnectOptions

sourceยง

fn default() -> MySqlConnectOptions

Returns the โ€œdefault valueโ€ for a type. Read more
sourceยง

impl FromStr for MySqlConnectOptions

ยง

type Err = Error

The associated error which can be returned from parsing.
sourceยง

fn from_str(s: &str) -> Result<MySqlConnectOptions, Error>

Parses a string s to return a value of this type. Read more
sourceยง

impl<'a> TryFrom<&'a AnyConnectOptions> for MySqlConnectOptions

ยง

type Error = Error

The type returned in the event of a conversion error.
sourceยง

fn try_from( any_opts: &'a AnyConnectOptions ) -> Result<MySqlConnectOptions, <MySqlConnectOptions as TryFrom<&'a AnyConnectOptions>>::Error>

Performs the conversion.

Auto Trait Implementationsยง

Blanket Implementationsยง

sourceยง

impl<T> Any for T
where T: 'static + ?Sized,

sourceยง

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
sourceยง

impl<T> Borrow<T> for T
where T: ?Sized,

sourceยง

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
sourceยง

impl<T> BorrowMut<T> for T
where T: ?Sized,

sourceยง

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
sourceยง

impl<T> From<T> for T

sourceยง

fn from(t: T) -> T

Returns the argument unchanged.

sourceยง

impl<T> Instrument for T

sourceยง

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
sourceยง

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
sourceยง

impl<T, U> Into<U> for T
where U: From<T>,

sourceยง

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

sourceยง

impl<T> Same for T

ยง

type Output = T

Should always be Self
sourceยง

impl<T> ToOwned for T
where T: Clone,

ยง

type Owned = T

The resulting type after obtaining ownership.
sourceยง

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
sourceยง

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
sourceยง

impl<T, U> TryFrom<U> for T
where U: Into<T>,

ยง

type Error = Infallible

The type returned in the event of a conversion error.
sourceยง

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
sourceยง

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

ยง

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
sourceยง

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
sourceยง

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

sourceยง

fn vzip(self) -> V

sourceยง

impl<T> WithSubscriber for T

sourceยง

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
sourceยง

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more