Struct sqlx::mysql::MySqlConnectOptions
source ยท pub struct MySqlConnectOptions { /* private fields */ }
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
Parameter | Default | Description |
---|---|---|
ssl-mode | PREFERRED | Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated. See MySqlSslMode . |
ssl-ca | None | Sets the name of a file containing a list of trusted SSL Certificate Authorities. |
statement-cache-capacity | 100 | The maximum number of prepared statements stored in the cache. Set to 0 to disable. |
socket | None | Path 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
impl MySqlConnectOptions
sourcepub fn new() -> MySqlConnectOptions
pub fn new() -> MySqlConnectOptions
Creates a new, default set of options ready for configuration
sourcepub fn host(self, host: &str) -> MySqlConnectOptions
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.
sourcepub fn port(self, port: u16) -> MySqlConnectOptions
pub fn port(self, port: u16) -> MySqlConnectOptions
Sets the port to connect to at the server host.
The default port for MySQL is 3306
.
sourcepub fn socket(self, path: impl AsRef<Path>) -> MySqlConnectOptions
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
.
sourcepub fn username(self, username: &str) -> MySqlConnectOptions
pub fn username(self, username: &str) -> MySqlConnectOptions
Sets the username to connect as.
sourcepub fn password(self, password: &str) -> MySqlConnectOptions
pub fn password(self, password: &str) -> MySqlConnectOptions
Sets the password to connect with.
sourcepub fn database(self, database: &str) -> MySqlConnectOptions
pub fn database(self, database: &str) -> MySqlConnectOptions
Sets the database name.
sourcepub fn ssl_mode(self, mode: MySqlSslMode) -> MySqlConnectOptions
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);
sourcepub fn ssl_ca(self, file_name: impl AsRef<Path>) -> MySqlConnectOptions
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");
sourcepub fn ssl_ca_from_pem(self, pem_certificate: Vec<u8>) -> MySqlConnectOptions
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![]);
sourcepub fn ssl_client_cert(self, cert: impl AsRef<Path>) -> MySqlConnectOptions
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");
sourcepub fn ssl_client_cert_from_pem(
self,
cert: impl AsRef<[u8]>
) -> MySqlConnectOptions
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);
sourcepub fn ssl_client_key(self, key: impl AsRef<Path>) -> MySqlConnectOptions
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");
sourcepub fn ssl_client_key_from_pem(
self,
key: impl AsRef<[u8]>
) -> MySqlConnectOptions
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);
sourcepub fn statement_cache_capacity(self, capacity: usize) -> MySqlConnectOptions
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.
sourcepub fn charset(self, charset: &str) -> MySqlConnectOptions
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
.
sourcepub fn collation(self, collation: &str) -> MySqlConnectOptions
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
.
sourcepub fn pipes_as_concat(self, flag_val: bool) -> MySqlConnectOptions
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.
sourcepub fn enable_cleartext_plugin(self, flag_val: bool) -> MySqlConnectOptions
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.
sourcepub fn no_engine_subsitution(self, flag_val: bool) -> MySqlConnectOptions
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/
sourcepub fn timezone(self, value: impl Into<Option<String>>) -> MySqlConnectOptions
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.
sourcepub fn set_names(self, flag_val: bool) -> MySqlConnectOptions
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
impl MySqlConnectOptions
sourcepub fn get_host(&self) -> &str
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");
sourcepub fn get_port(&self) -> u16
pub fn get_port(&self) -> u16
Get the serverโs port.
ยงExample
let options = MySqlConnectOptions::new()
.port(6543);
assert_eq!(options.get_port(), 6543);
sourcepub fn get_socket(&self) -> Option<&PathBuf>
pub fn get_socket(&self) -> Option<&PathBuf>
Get the socket path.
ยงExample
let options = MySqlConnectOptions::new()
.socket("/tmp");
assert!(options.get_socket().is_some());
sourcepub fn get_username(&self) -> &str
pub fn get_username(&self) -> &str
Get the serverโs port.
ยงExample
let options = MySqlConnectOptions::new()
.username("foo");
assert_eq!(options.get_username(), "foo");
sourcepub fn get_database(&self) -> Option<&str>
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());
sourcepub fn get_ssl_mode(&self) -> MySqlSslMode
pub fn get_ssl_mode(&self) -> MySqlSslMode
Get the SSL mode.
ยงExample
let options = MySqlConnectOptions::new();
assert!(matches!(options.get_ssl_mode(), MySqlSslMode::Preferred));
sourcepub fn get_charset(&self) -> &str
pub fn get_charset(&self) -> &str
Get the server charset.
ยงExample
let options = MySqlConnectOptions::new();
assert_eq!(options.get_charset(), "utf8mb4");
sourcepub fn get_collation(&self) -> Option<&str>
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
impl Clone for MySqlConnectOptions
sourceยงfn clone(&self) -> MySqlConnectOptions
fn clone(&self) -> MySqlConnectOptions
1.0.0 ยท sourceยงfn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresourceยงimpl ConnectOptions for MySqlConnectOptions
impl ConnectOptions for MySqlConnectOptions
type Connection = MySqlConnection
sourceยงfn from_url(url: &Url) -> Result<MySqlConnectOptions, Error>
fn from_url(url: &Url) -> Result<MySqlConnectOptions, Error>
ConnectOptions
from a URL.sourceยงfn to_url_lossy(&self) -> Url
fn to_url_lossy(&self) -> Url
ConnectOptions
. Read moresourceยงfn connect(
&self
) -> Pin<Box<dyn Future<Output = Result<<MySqlConnectOptions as ConnectOptions>::Connection, Error>> + Send + '_>>
fn connect( &self ) -> Pin<Box<dyn Future<Output = Result<<MySqlConnectOptions as ConnectOptions>::Connection, Error>> + Send + '_>>
self
.sourceยงfn log_statements(self, level: LevelFilter) -> MySqlConnectOptions
fn log_statements(self, level: LevelFilter) -> MySqlConnectOptions
level
sourceยงfn log_slow_statements(
self,
level: LevelFilter,
duration: Duration
) -> MySqlConnectOptions
fn log_slow_statements( self, level: LevelFilter, duration: Duration ) -> MySqlConnectOptions
duration
at the specified level
.