Perl DBI "install_driver(X) failed" in CI

DBI tried to load a DBD::* driver at connect time and could not: either the driver module is not installed, or its native client library is absent. The message names the driver and the reason.

What this error means

A connect dies with "install_driver(mysql) failed: Can't locate DBD/mysql.pm in @INC" or "libmysqlclient.so: cannot open shared object file".

perl

install_driver(mysql) failed: Can't locate DBD/mysql.pm in @INC
(you may need to install the DBD::mysql module) at (eval 3) line 2.

Common causes

The DBD driver is not installed

DBI is generic; each database needs its own DBD::* driver (DBD::mysql, DBD::Pg, DBD::SQLite), which was never installed on the runner.

The driver client library is missing

DBD::mysql links libmysqlclient and DBD::Pg links libpq; without the client -dev/runtime package the driver fails to build or load.

How to fix it

Install the DB client library then the driver

Install the database client -dev package the driver links against.
Install the DBD::* driver with cpanm.
Re-run so install_driver can load it.

Terminal

sudo apt-get update
sudo apt-get install -y default-libmysqlclient-dev
cpanm --notest DBD::mysql

Provide the database as a service

For integration tests, run the database as a CI service and point DBI at it.

.github/workflows/ci.yml

services:
  mysql:
    image: mysql:8
    env:
      MYSQL_ROOT_PASSWORD: root

How to prevent it

Install the DBD driver and its client library in a setup step.
Run databases as CI services for integration tests.
Pin driver versions in the cpanfile.