mysql_async

You can choose between two TLS implementations:

1. native-tls: The default option (via native-tls-tls feature). Generally works without pitfalls.
2. rustls: A Rust-based TLS backend (via rustls-tls feature).

Important considerations for rustls:

• You must connect using a hostname; connecting via IP address will fail.
• It may not work on Windows with default server certificates generated by the MySQL installer.

When the server issues a LOCAL INFILE request, the driver searches for a handler in the following order of priority:

1. Local Handler: A one-time handler installed directly on the connection via Conn::set_infile_handler. This has the highest priority.
2. Global Handler: A handler specified via OptsBuilder::local_infile_handler. This is used if no local handler is present.
3. Error: If neither is found, the driver emits LocalInfileError::NoHandler.

Security Warning: Always review Security Considerations for LOAD DATA LOCAL before implementing handlers.

To run tests properly, you must use a MySQL server configured with specific parameters (max allowed packet, local-infile, and binary logging). Use the following command to start a compatible container:

docker run -d --name container \
    -v `pwd`:/root \
    -p 3307:3306 \
    -e MYSQL_ROOT_PASSWORD=password \
    mysql:8.0 \
    --max-allowed-packet=36700160 \
    --local-infile \
    --log-bin=mysql-bin \
    --log-slave-updates \
    --gtid_mode=ON \
    --enforce-gtid-consistency=ON \
    --server-id=1

To use mysql_async in your Rust project, add it to your Cargo.toml dependencies. You can specify a version or use * for the latest.

[dependencies]
mysql_async = "<desired version>"

The Pool must not be shared across independent tokio runtimes. Each connection's underlying TcpStream is bound to the I/O driver of the runtime that established it. If a runtime shuts down, those connections become invalid.

Best Practice: If your framework (like actix-server) runs each worker on its own current_thread runtime, create a separate Pool instance per worker instead of sharing one across all workers.

The AsQuery trait defines types that can be treated as a MySQL query. Because MySQL does not require queries to be valid UTF-8, this trait is implemented for both string-like types and byte-slice types.

Supported types include:

• Strings: &str, String, Box<str>, Cow<'_, str>, std::sync::Arc<str>
• Bytes: &[u8], Vec<u8>, Box<[u8]>, Cow<'_, [u8]>, std::sync::Arc<[u8]>

The Pool structure manages an asynchronous connection pool.

Key characteristics:

• Pool is a smart pointer; cloning it points to the same underlying pool instance.
• It is Send + Sync + 'static and can be safely passed between tasks.
• Pool::new is lazy and does not verify if the server is available immediately.
• Use pool.disconnect().await to gracefully close the pool.

Example usage:

let pool = mysql_async::Pool::new(database_url);
let mut conn = pool.get_conn().await?;
// ... use connection ...
drop(conn);
pool.disconnect().await?;

The ToConnection trait provides a polymorphic way to acquire a Connection.

• Pool or &Pool: Calling to_connection() returns a ToConnectionResult::Mediate containing a future that fetches a connection from the pool via get_conn().
• Conn: Calling to_connection() returns a ToConnectionResult::Immediate because the connection is already owned.
• Transaction: Can also be converted into a Connection to allow transaction-scoped queries.

By using ToConnection, you can write APIs that are agnostic to whether the caller provides a single connection or a connection pool.