PHP8.1-fpm: pdo-mysql installed but not appear on php -m
You've just finished spinning up a fresh php8.1-fpm stack alongside Apache2 and FGPI, confident that your environment is production-ready. You run sudo apt-get install php8.1-pdo-mysql, expecting the database module to load immediately. Instead, you hit a wall: php -m shows no trace of pdo_mysql. Even worse, running phpenmod pdo_mysql triggers a warning that the ini file doesn't exist in /etc/php/8.1/mods-available.
This isn't a configuration error; it's a specific quirk in how Debian-based systems handle PHP package dependencies for version 8.1.
The Dependency Trap
The root of the issue lies in the package manager's behavior during installation. When you attempt to install php8.1-pdo-mysql, the APT system often detects that php8.1-mysql is already present or prioritizes it as a dependency. As seen in your logs, the command effectively resolves to installing php8.1-mysql instead.
While php8.1-mysql provides the MySQL client libraries and extensions, the actual PDO driver files are sometimes expected to be generated by a specific build process that didn't trigger automatically. In older PHP versions or different distributions, this might have been handled seamlessly. However, in PHP 8.1 on Debian/Ubuntu, the package php8.1-mysql does not always generate the necessary .ini files in the mods-available directory required by the FPM configuration structure.
The result is a mismatch: the system thinks the module is installed because the library files exist, but the PHP-FPM configuration expects specific ini files to be present to load the extension properly.
Why phpenmod Fails
When you execute sudo phpenmod pdo_mysql, the tool looks for a file named pdo_mysql.ini in the /etc/php/8.1/mods-available directory. Since this file was never created by the package installation, the command fails with the warning you observed. Without this ini file, the extension cannot be loaded into the PHP runtime, even if the underlying C library is present.
The Solution: Force the Extension File
To resolve this without a full system reinstall, you need to manually create the missing configuration file. This tells the PHP-FPM worker processes explicitly which extensions to load.
You can generate the necessary ini file by copying it from the common pool or creating it manually with the correct syntax. The most reliable approach is to ensure the extension is loaded in the main configuration file used by your FPM pool, but first, let's fix the mods-available expectation.
Run the following command to create the missing ini file:
sudo tee /etc/php/8.1/fpm/mods-available/pdo_mysql.ini > /dev/null <<'EOF'
extension=pdo_mysql.so
EOF
Alternatively, if you prefer to use the standard Debian template approach, check if a symlink exists in mods-enabled. If it's missing, create it:
sudo ln -s /etc/php/8.1/fpm/mods-available/pdo_mysql.ini /etc/php/8.1/fpm/conf.d/20-pdo_mysql.ini
Once the file is in place, restart your PHP-FPM service to apply the changes:
sudo systemctl restart php8.1-fpm
Verification
After the restart, run php -m again. You should now see pdo_mysql listed alongside your existing modules like redis, xml, and xdebug. If you are running a Laravel application or similar framework, verify that your connection is working by checking the database status within the application context.
A Note on Package Management
This behavior highlights a common pitfall when mixing PHP versions and managing extensions via apt on Debian derivatives. While apt is convenient for bulk updates, it sometimes obscures the exact state of extension files versus configuration files. If you find yourself in a situation where phpenmod warns about missing ini files despite packages being installed, manually generating the .ini file is often the quickest fix.
If you are deploying a larger application stack and encounter persistent issues with PHP 8.1 extensions not loading automatically, consider checking your /etc/php/8.1/fpm/conf.d directory. Sometimes, conflicts between multiple extension files or incorrect priority numbers can prevent modules from initializing correctly. Ensure that pdo_mysql.ini is present and enabled in the specific pool configuration you are using for your web server.
For developers managing complex PHP environments, understanding the distinction between library packages (php8.1-mysql) and driver packages (php8.1-pdo-mysql) is crucial. The former provides connectivity libraries, while the latter ensures the PDO interface is available to the application code.