为何gem mysql2 0.3.x版本安装失败但0.4.x及以上版本可正常安装？

mysql2 0.3.21为停止维护的老旧版本，仅兼容MySQL 5.7及更早版本、MariaDB 10.2及更早版本的客户端库，与新版客户端库存在兼容性问题，可按以下步骤修复： #

第一步：清理现有不兼容依赖 #

• 卸载已安装的对应版本mysql2 gem：gem uninstall mysql2 -v 0.3.21
• 移除系统中已安装的新版客户端开发包：sudo apt remove --purge -y libmariadb-dev libmysqlclient-dev

第二步：安装兼容版本的MySQL客户端开发库 #

Ubuntu/Debian系系统可通过旧版源安装MySQL 5.7版本的开发包：

sudo apt install -y software-properties-common
sudo add-apt-repository -y 'deb http://archive.ubuntu.com/ubuntu bionic main universe'
sudo apt update
sudo apt install -y libmysqlclient-dev=5.7.33-0ubuntu0.18.04.1
# 锁定版本避免后续自动升级
sudo apt-mark hold libmysqlclient-dev

第三步：指定编译参数安装mysql2 gem #

gem install mysql2 -v '0.3.21' -- --with-mysql-config=/usr/bin/mysql_config
# 项目目录下执行确认安装成功
bundle install

第四步：修复rake db:create运行报错 #

该报错为客户端与服务端版本不兼容或认证配置错误导致，按以下方式排查：

• 确认本地MySQL/MariaDB服务端版本不高于MySQL 5.7、MariaDB 10.2，版本过高需降级服务端
• 若使用高版本服务端且无法降级，进入MySQL命令行执行以下命令调整认证插件：

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '你的数据库密码';
FLUSH PRIVILEGES;

• 在项目config/database.yml的默认配置块中添加兼容参数：

default: &default
  adapter: mysql2
  encoding: utf8
  pool: 5
  username: 你的数据库用户名
  password: 你的数据库密码
  host: localhost
  options:
    - MYSQL_SECURE_AUTH=0

额外注意事项 #

• 避免使用sudo安装Ruby gem，推荐使用rbenv或rvm管理Ruby版本及gem集，避免权限冲突
• 若系统已安装多个MySQL版本，需将--with-mysql-config后的路径替换为对应5.7版本的mysql_config可执行文件路径

内容的提问来源于stack exchange，提问作者Gaurav Singh