Struct sqlx::MySqlConnection

pub struct MySqlConnection { /* fields omitted */ }

This is supported on feature="mysql" only.

An asynchronous connection to a MySql database.

The connection string expected by [Connection::open] should be a MySQL connection string, as documented at https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri

TLS Support (requires tls feature)

This connection type supports some of the same flags as the mysql CLI application for SSL connections, but they must be specified via the query segment of the connection string rather than as program arguments.

The same options for --ssl-mode are supported as the ssl-mode query parameter: https://dev.mysql.com/doc/refman/8.0/en/connection-options.html#option_general_ssl-mode

mysql://<user>[:<password>]@<host>[:<port>]/<database>[?ssl-mode=<ssl-mode>[&ssl-ca=<path>]]

where

ssl-mode = DISABLED | PREFERRED | REQUIRED | VERIFY_CA | VERIFY_IDENTITY
path = percent (URL) encoded path on the local machine

If the tls feature is not enabled, ssl-mode=DISABLED and ssl-mode=PREFERRED are no-ops and ssl-mode=REQUIRED, ssl-mode=VERIFY_CA and ssl-mode=VERIFY_IDENTITY are forbidden (attempting to connect with these will return an error).

If the tls feature is enabled, an upgrade to TLS is attempted on every connection by default (equivalent to ssl-mode=PREFERRED). If the server does not support TLS (because --ssl=0 was passed to the server or an invalid certificate or key was used: https://dev.mysql.com/doc/refman/8.0/en/using-encrypted-connections.html) then it falls back to an unsecured connection and logs a warning.

Add ssl-mode=REQUIRED to your connection string to emit an error if the TLS upgrade fails.

However, like with mysql the server certificate is not checked for validity by default.

Specifying ssl-mode=VERIFY_CA will cause the TLS upgrade to verify the server's SSL certificate against a local CA root certificate; this is not the system root certificate but is instead expected to be specified as a local path with the ssl-ca query parameter (percent-encoded so the URL remains valid).

If you're running MySQL locally it might look something like this (for VERIFY_CA):

mysql://root:password@localhost/my_database?ssl-mode=VERIFY_CA&ssl-ca=%2Fvar%2Flib%2Fmysql%2Fca.pem

%2F is the percent-encoding for forward slash (/). In the example we give /var/lib/mysql/ca.pem as the CA certificate path, which is generated by the MySQL server automatically if no certificate is manually specified. Note that the path may vary based on the default my.cnf packaged with MySQL for your Linux distribution. Also note that unlike MySQL, MariaDB does not generate certificates automatically and they must always be passed in to enable TLS.

If ssl-ca is not specified or the file cannot be read, then an error is returned. ssl-ca implies ssl-mode=VERIFY_CA so you only actually need to specify the former but you may prefer having both to be more explicit.

If ssl-mode=VERIFY_IDENTITY is specified, in addition to checking the certificate as with ssl-mode=VERIFY_CA, the hostname in the connection string will be verified against the hostname in the server certificate, so they must be the same for the TLS upgrade to succeed. ssl-ca must still be specified.

Methods

impl MySqlConnection

pub fn open<T>(
    url: T
) -> Pin<Box<dyn Future<Output = Result<MySqlConnection, Error>> + 'static + Send>> where
    T: TryInto<Url, Error = Error>,
    MySqlConnection: Sized, 

Deprecated:

please use 'connect' instead

This is supported on feature="mysql" only.

Trait Implementations

impl Connect for MySqlConnection

type Connection = MySqlConnection

fn connect<T>(
    url: T
) -> Pin<Box<dyn Future<Output = Result<MySqlConnection, Error>> + 'static + Send>> where
    T: TryInto<Url, Error = Error>,
    MySqlConnection: Sized, 

Establish a new database connection.

impl Connection for MySqlConnection

fn close(
    self
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'static + Send>>

Close this database connection.

fn ping(&mut self) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>

Verifies a connection to the database is still alive.

impl Executor for MySqlConnection

type Database = MySql

fn send<'e, 'q>(
    &'e mut self,
    query: &'q str
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'e + Send>> where
    'q: 'e, 

Send a raw SQL command to the database.

fn execute<'e, 'q>(
    &'e mut self,
    query: &'q str,
    args: MySqlArguments
) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + 'e + Send>> where
    'q: 'e, 

Execute the query, returning the number of rows affected.

fn fetch<'e, 'q>(
    &'e mut self,
    query: &'q str,
    args: MySqlArguments
) -> Pin<Box<dyn Stream<Item = Result<MySqlRow, Error>> + 'e + Send>> where
    'q: 'e, 

Executes the query and returns a [Stream] of [Row].

fn describe<'e, 'q>(
    &'e mut self,
    query: &'q str
) -> Pin<Box<dyn Future<Output = Result<Describe<<MySqlConnection as Executor>::Database>, Error>> + 'e + Send>> where
    'q: 'e, 

fn fetch_optional<'e, 'q>(
    &'e mut self,
    query: &'q str,
    args: <Self::Database as Database>::Arguments
) -> Pin<Box<dyn Future<Output = Result<Option<<Self::Database as Database>::Row>, Error>> + 'e + Send>> where
    'q: 'e, 

Executes the query and returns up to resulting record.

fn fetch_one<'e, 'q>(
    &'e mut self,
    query: &'q str,
    args: <Self::Database as Database>::Arguments
) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Row, Error>> + 'e + Send>> where
    'q: 'e, 

Execute the query and return at most one resulting record.