mysql_async

mysql_async is a fully asynchronous MySQL driver for Rust built on top of Tokio, implementing both the text and binary (prepared statement) query protocols directly against the MySQL wire format rather than wrapping a C client library. That gives it native async I/O, streaming result sets, and fine-grained control over connection lifecycle without blocking executor threads.

The crate ships a configurable connection pool with min/max sizing, idle and absolute TTLs with jitter, and a background recycler for connection reuse; named and positional parameter binding via the params! macro; optional binlog streaming; and pluggable TLS backends through native-tls or rustls. It builds on the shared mysql_common crate for wire-protocol types and value conversions, keeping its data-type handling consistent with the synchronous mysql crate from the same maintainer.

What You Get

• Async connection pool with configurable min/max size, idle TTL, absolute TTL with jitter, and a background recycler
• Both text and binary (prepared statement) MySQL protocols via the Queryable trait
• Named parameter binding (:name syntax) and positional parameters through the params! macro
• Transaction helper with automatic rollback-on-drop semantics
• Pluggable TLS via native-tls or rustls (with ring/aws-lc-rs providers), plus optional binlog streaming

Common Use Cases

• Powering async web services (Axum, Actix-web, etc.) that read/write MySQL or MariaDB without blocking the executor
• Building connection-pooled backends that need fine control over pool sizing and idle-connection lifetime
• Streaming large result sets or binlog replication events without buffering the entire result in memory
• Batch-inserting or updating rows via prepared statements with named parameters

Under The Hood

Architecture The crate is organized into clearly separated modules: conn (the Conn type and its pool submodule), connection_like (a shared abstraction over plain connections and pooled connections), queryable (the text/binary protocol implementations, Transaction, and Statement), opts (URL and builder-based connection configuration, with TLS options split into native_tls_opts/rustls_opts), io (transport and TLS I/O), and error (a typed error hierarchy). The pool internals (src/conn/pool/) are the most sophisticated part of the design: a Recycler runs as a background task driving FuturesUnordered sets for connections being cleaned, reset, or discarded, coordinated through mpsc channels and an atomics-backed Waitlist/InPoolConnections structure rather than a single global lock. Feature flags (rustls-tls, native-tls-tls, binlog, tracing, and per-value-type features proxied from mysql_common) let consumers compile in only the transport and conversion code they need.

Tech Stack Built on Tokio (io-util, fs, net, time, rt, sync features) with futures-core/futures-util/futures-sink for stream and future composition, bytes and tokio-util (codec/io) for wire-level buffering, and crossbeam-queue/crossbeam-utils/keyed_priority_queue/lru for pool and statement-cache data structures. Protocol types and value conversions are delegated to the sibling mysql_common crate. TLS is pluggable between native-tls/tokio-native-tls and rustls/tokio-rustls (with webpki-roots and selectable aws-lc-rs/ring crypto providers), and flate2 provides optional wire compression with a choice of system zlib or a pure-Rust backend.

Code Quality Errors are modeled as a typed Error enum (Driver, Io, Other, Server, Url variants) built with thiserror, with an is_fatal() helper for distinguishing connection-ending errors from recoverable ones — a notably more structured approach than string-based error handling. The crate carries extensive inline documentation (over a thousand doc comments across roughly fifty source files) and dozens of inline #[test]/#[tokio::test] unit tests across pool, transaction, and options modules, plus integration tests in tests/. CI (Azure Pipelines) runs the full suite against a live MySQL server on stable, beta, and nightly Rust, and enforces cargo fmt --check, giving reasonable confidence the async pool logic is exercised under real conditions rather than mocked.

What Makes It Unique Rather than binding to libmysqlclient or another C driver, mysql_async implements the MySQL wire protocol itself, which is what allows it to be genuinely non-blocking end-to-end and to expose primitives most C-backed drivers can’t, such as BinlogStream for consuming MySQL’s replication stream directly and a pool with independently tunable idle and absolute connection TTLs (with jitter, to avoid thundering-herd reconnects). It is a comprehensive, production-grade async driver rather than a novel architectural pattern — its distinguishing value is the depth and correctness of its pool and protocol implementation, not a new concept in the space.