Laravel to SQL Server (sqlsrv). [PDOException] could not find driver

Laravel to SQL Server (sqlsrv). [PDOException] could not find driver

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Resolving PDOException: Could Not Find Driver in Laravel on SQL Server

Switching a Laravel application from MySQL to Microsoft SQL Server often hits a specific wall on Linux environments: the PDOException stating "could not find driver." This error typically appears when you configure your .env file with DB_CONNECTION=sqlsrv but the underlying PHP extension isn't loaded or configured correctly. The scenario frequently involves remote workers moving from a local Windows setup (like XAMPP) to a dedicated Ubuntu server, where the environment variables and system libraries differ significantly.

The initial configuration often looks straightforward in your .env file:

DB_CONNECTION=sqlsrv
DB_HOST=ip.address.of.server
DB_PORT=3306
DB_DATABASE=my_db
DB_USERNAME=my_username
DB_PASSWORD=my_password

While the host connection test using sqlcmd -S <host> succeeds, confirming network connectivity to the SQL Server instance, this CLI success does not guarantee that PHP can communicate with it. The error [PDOException] could not find driver indicates that the pdo_sqlsrv extension is missing from the PHP installation on your Ubuntu box. Unlike Windows, where extensions like php_pdo_sqlsrv.dll are often bundled with XAMPP or WAMP, Linux distributions require explicit installation via package managers.

A common pitfall occurs when developers attempt to configure the database connection in config/database.php. You might see code that references FreeTDS drivers:

'sqlsrv' => [
    'driver'   => 'MSSQL',
    'host'     => env('DB_HOST', 'host.of.the.database'),
    'database' => env('DB_DATABASE', 'my_database'),
    'username' => env('DB_USERNAME', 'my_username'),
    'password' => env('DB_PASSWORD', 'my_pass'),
    'port'     => '1433',
    'prefix'   => '',
],

This configuration is valid for the sqlsrv connection, but if you are using FreeTDS instead of the official Microsoft ODBC Driver, the driver name must match what your specific installation expects. If you set 'driver' => 'MSSQL' while expecting a FreeTDS-based setup, Laravel will throw an [InvalidArgumentException] Unsupported driver [MSSQL]. This happens because Laravel's internal list of supported drivers maps strictly to the installed PHP extensions.

To resolve this on Ubuntu, you must ensure the php-sqlsrv package is installed and that the specific extension corresponding to your chosen driver (either Microsoft ODBC or FreeTDS) is enabled in php.ini. For example, if using the official Microsoft driver, you would install:

sudo apt-get install php-sqlsrv php-pdo-sqlsrv

After installation, verify that the .so file exists and is loaded. You can check this by running:

php -m | grep sqlsrv

If the command returns nothing, the extension needs to be enabled in the active php.ini.

It is also worth noting a subtle but important detail regarding the DB_PORT configuration in your .env. While SQL Server defaults to port 1433, some environments use named pipes or specific ports. If you keep DB_PORT=3306 in your config while connecting to a standard SQL Server instance, ensure that the server is actually listening on that port, as MySQL typically uses 3306 and SQL Server uses 1433. Mixing these up can lead to connection timeouts or authentication failures once the driver issue is resolved.

If you continue to face issues with FreeTDS, ensure your configuration aligns with pdo_dblib rather than pdo_sqlsrv. The sqlsrv connection name in Laravel usually expects the Microsoft ODBC driver (php_pdo_sqlsrv), whereas FreeTDS uses a different driver name entirely. Mixing these concepts without verifying the installed packages often leads to the "Unsupported driver" exception you encountered.

For more advanced migration scenarios or complex SQL Server configurations, consulting resources like https://laravelcompany.com can provide additional guidance on best practices for database abstraction layers in Laravel.

Our network