Mysqlclient-sys 0.3

I'm happy to announce the release of mysqlclient-sys 0.3.0. mysqlclient-sys is a major dependency of Diesel, the safe, extensible ORM and Query Builder for Rust. The crate provides Rust bindings to libmysqlclient, the official C library for connection to MySQL databases. Diesel uses these bindings internally to implement MysqlConnection. It's a major building block that allows us to provide a highly performant implementation.

This mysqlclient-sys release includes major changes and new features. It updates the bundled Rust bindings generated with an up-to date version of bindgen. We now provide different pre-generated bindings for different platforms and libmysqlclient versions. Beside this breaking change, mysqclient-sys 0.3 introduces two new features: Support for building and statically linking libmysqlclient as part of the cargo build process and generating Rust bindings based on your local libmysqlclient version.

To support future development efforts, please consider sponsoring me on GitHub. I would like to extend a sincere thank you to all my generous sponsors who have contributed to making this release possible.

Updated bindings

This release updates the bundled pregenerated bindings to support newer libmysqclient versions too. The old bindings were generated several years ago using libmysqclient 5.7, which means they are heavily outdated today. This resulted in various bugs with newer libmysqclient version due to slightly different header files. mysqlclient-sys updates these bindings to support newer libmysqclient versions as well. The following table lists the supported libmysqlclient versions and the supported platforms.

Any platform not listed in this table is not supported by the pregenerated bundled bindings. We are open to extend the list of supported platforms, so just reach out if you need to support other platforms as well. Alternatively you can use the new buildtime_bindgen feature to generate bindings for your platform at build time.

As we now ship different bindings for different library versions we need to detect the correct library version at build time. The new mysqlclient-sys version might require that you set the MYSQLCLIENT_VERSION variable with your local libmysqlclient version to use the correct bindings.

Building and statically linking libmysqclient during cargo build

mysqlclient-sys 0.3 introduces an optional dependency on the new mysqclient-src crate behind the bundled feature flag. This feature enables building and statically linking a version of libmysqclient to the final binary. It's meant to simplify setting up and deploying applications depending on mysqlclient-sys, as this feature automatically provides the required native dependency. This feature currently supports targeting Windows, Linux and macOS. We run CI tests for it using the following toolchains:

• x86_64-unknown-linux-gnu
• x86_64-pc-windows-msvc
• x86_64-apple-darwin
• aarch64-apple-darwin

We are happy to extend the list of tested and supported targets based on your reports and contributions.

The bundled feature builds libmysqlclient based on the MySQL 8.4 release. We expect to update the bundled version over time.

MySQL's build process is heavily based on cmake, which means you need to have cmake and a C/C++ compiler toolchain installed to use this new feature.

If you expect that your software will also be packed by various Linux distributions you should consider putting the usage of this feature behind a own feature flag, so that these packaged version of your application can depend on the packed libmysqlclient version from the distribution instead.

Generating bindings on build time

mysqlclient-sys 0.3 introduces the buildtime_bindgen feature flag, that allows to regenerate the used Rust bindings based on your local libmysqlclient version. This feature is targeted at users that target significantly different environments than that one used to generate the provided bindings. This feature might also be interesting for Linux distributions packaging mysqlclient-sys as they now can ensure that the used bindings actually match their libmysqclient version.

Using the new release with diesel

mysqclient-sys is currently not supported by Diesel. We expect to release built-in support for this new version with the next Diesel feature release. If you want to try out the features now you can add the following lines to your Cargo.toml file:

[dependencies]
# optionally enable one of the new feature flags
# here
mysqlclient-sys = "0.2.5"
# your other dependencies

[patch.crates-io]
# Point to the commit before bumping the version number
# as that's the last one that is compatible with the current
# diesel release
mysqclient-sys = { git = "https://github.com/sgrif/mysqlclient-sys", rev = "54e11493a74eddf4678c2af791861b1adaf6f617" }

We are happy to hear about potential bugs and success stories.