Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

PHP throws "could not find driver" when it opens a PDO connection

ErrorPDOException: could not find driver

Short answer

PDO is only a layer; each database needs its own driver extension, such as pdo_mysql or pdo_pgsql, and the DSN prefix must name a driver that is loaded. The error means the PHP process that ran the code has no such driver. Check PDO::getAvailableDrivers() in that same runtime, because the command line and PHP-FPM often load different ini files.

  • Applies to PHP 8.3, PHP 8.4, pdo_mysql, pdo_pgsql, PHP-FPM and CLI on Linux, official php Docker image
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the runtime that failed which drivers it has. The command line and the web server are separate PHP processes with their own ini files, so a command that works in your terminal proves nothing about the web. Put the check in a script served through the web server, and run the same script on the command line to compare.

    <?php
    // drivers.php: request it through the web server, then run: php drivers.php
    header('Content-Type: text/plain');
    echo php_sapi_name(), "\n";
    echo 'php.ini: ', var_export(php_ini_loaded_file(), true), "\n";
    echo 'scanned: ', php_ini_scanned_files() ?: '(none)', "\n";
    echo 'drivers: ', implode(', ', PDO::getAvailableDrivers()), "\n";
  2. 2Match what you see, then jump to its fix

    1. 1getAvailableDrivers() prints nothing or only sqlite, in both the CLI and the web run, and php -m has no pdo_mysql or pdo_pgsql.The driver extension is not installedFix
    2. 2php -m shows pdo_mysql, but the web request fails. The drivers.php output differs between the two runs: a different php.ini path, or a different list of scanned files.The CLI has the driver but PHP-FPM or Apache loads a different ini fileFix
    3. 3PHP prints a startup warning such as "Unable to load dynamic library" in the error log or with php -i, while the driver is still missing from the list.The extension line is there but the driver does not loadFix
    4. 4Another driver works, but the one in the DSN is absent from the list, for example a pgsql: DSN while only mysql is listed.The DSN names a driver you did not installFix

What does the error look like?

  • PDOException: could not find driver
  • Fatal error: Uncaught PDOException: could not find driver in /var/www/app/db.php:12
  • Illuminate\Database\QueryException: could not find driver (Connection: mysql, SQL: ...)

Cause 1 of 4

The driver extension is not installed

1Check

PDO and its sqlite driver come with PHP, but the PHP manual says you may need to enable the driver for your own database. List what the CLI has, then look for the driver in your package manager or build.

php -m | grep -i pdo
# Debian/Ubuntu: find the packages that match your PHP version
apt-cache search --names-only 'php.*(mysql|pgsql)'

2Fix

Install the driver for the PHP version you run, then restart whatever runs PHP. In the official php Docker image the extensions are built with the image's own helper; pdo_pgsql also needs the PostgreSQL client library (libpq) available when it is built.

# package manager: pick the names apt-cache printed for your PHP version, for example
sudo apt install php8.3-mysql        # pdo_mysql
sudo apt install php8.3-pgsql        # pdo_pgsql
sudo systemctl restart php8.3-fpm

# official php Docker image (Dockerfile)
RUN docker-php-ext-install pdo_mysql

3Verify

The driver now appears in the list, in the runtime that failed.

php -r 'print_r(PDO::getAvailableDrivers());'

Confirmed by php.net

Did this fix it?

Cause 2 of 4

The CLI has the driver but PHP-FPM or Apache loads a different ini file

1Check

PHP picks php.ini by SAPI (the way PHP is run), so the CLI, FPM and Apache each have their own configuration, and each can scan a different extra directory. Compare the two outputs from the first step, then open the file the failing one reported.

php --ini
# the web side: request drivers.php and read php.ini / scanned
curl -s http://localhost/drivers.php

2Fix

Enable the driver in the ini that the failing SAPI loads. Debian-style packages normally do this with one line per extension in that SAPI's conf.d directory. Whatever the layout, list pdo before the driver, and restart the web-side process afterwards because the ini is only read at startup.

; the file the web SAPI reported (path varies by distribution)
extension=pdo
extension=pdo_mysql
extension=pdo_pgsql

sudo systemctl restart php8.3-fpm     # or: sudo systemctl restart apache2

3Verify

Request the script again: the drivers line now lists the driver and both runs agree.

curl -s http://localhost/drivers.php | grep drivers

Confirmed by php.net

Did this fix it?

Cause 3 of 4

The extension line is there but the driver does not load

1Check

A line in php.ini is not enough: the extension file must exist inside extension_dir, a Windows build needs the file to be there too, and the PHP manual says PDO must be initialized before database-specific extensions, so the pdo line has to come first. Read PHP's own startup errors, and the directory it searches.

php -i 2>&1 | grep -iE 'warning|extension_dir'
ls "$(php -r 'echo ini_get("extension_dir");')" | grep -i pdo

2Fix

Correct the extension_dir or install the missing module, order the lines with pdo first, then restart. On Windows, uncomment the extension lines in php.ini and make sure the matching file exists in extension_dir.

extension_dir = "/usr/lib/php/20230831"   ; the directory that holds pdo_mysql.so on your system
extension=pdo
extension=pdo_mysql

3Verify

Start-up warnings are gone and the driver is listed.

php -i 2>&1 | grep -ci 'unable to load'     # expect 0
php -r 'print_r(PDO::getAvailableDrivers());'

Confirmed by php.net

Did this fix it?

Cause 4 of 4

The DSN names a driver you did not install

1Check

The text before the first colon in the DSN selects the driver: the PHP manual gives mysql: for MySQL and MariaDB and pgsql: for PostgreSQL. Compare it with the list from getAvailableDrivers(), which uses the same names.

grep -rnE "new PDO\(|DB_CONNECTION|DATABASE_URL" . --include=*.php --include=.env 2>/dev/null | head
php -r 'echo implode(",", PDO::getAvailableDrivers());'

2Fix

Either install the driver that matches the database you really use, or correct the DSN prefix and parameters to the form the driver documents.

// MySQL or MariaDB
new PDO('mysql:host=127.0.0.1;port=3306;dbname=app;charset=utf8mb4', $user, $pass);
// PostgreSQL
new PDO('pgsql:host=127.0.0.1;port=5432;dbname=app', $user, $pass);

3Verify

The constructor now returns without exception.

php -r '$p = new PDO("mysql:host=127.0.0.1;dbname=app", "app", getenv("DB_PASSWORD")); echo $p->getAttribute(PDO::ATTR_DRIVER_NAME), "\n";'

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Keep a small diagnostics script (like drivers.php) for deployment checks, and run it through the web server, not only the terminal.
  • Install PHP and its extensions from one place per server, and write the extension list in the image or provisioning script rather than by hand.
  • Pin the PHP minor version in packages and restart FPM after every upgrade, since ini files and module directories are per version.
  • Fail the deploy when PDO::getAvailableDrivers() lacks the driver the app needs.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.