Ruby mysql2 Gem Build Fails - Missing libmysqlclient in CI

The mysql2 gem compiles a native extension that links against the MySQL/MariaDB client library. The build fails because libmysqlclient (and its headers) or mysql_config is not installed on the runner.

What this error means

bundle install fails with "An error occurred while installing mysql2", and the build log shows a missing mysql.h, a missing mysql_config, or a link error against libmysqlclient.

gem output

An error occurred while installing mysql2 (0.5.6), and Bundler cannot continue.

checking for mysql_config... no
ld: library not found for -lmysqlclient
*** extconf.rb failed ***

Common causes

MySQL client development files not installed

mysql2 needs the client headers and libmysqlclient to compile. The runtime MySQL package alone does not include the -dev files.

mysql_config not on PATH

When mysql_config is missing, extconf cannot locate the client library to link against, even if a server package is present.

How to fix it

Install the MySQL client dev package

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y libmysqlclient-dev
# or MariaDB client
apt-get install -y libmariadb-dev
# Alpine
apk add --no-cache mariadb-dev

Point the gem at mysql_config

If the client is in a non-standard prefix, tell the gem where mysql_config lives.