{"record":{"id":"f793547544c01fc9","repo":"phalcon/cphalcon","slug":"driver-not-supported-driver","errorCode":null,"errorMessage":"Driver not supported [{driver}]","messagePattern":"Driver not supported \\[(.+?)\\]","errorType":"exception","errorClass":"Phalcon\\DataMapper\\Pdo\\Exception\\DriverNotSupported","httpStatus":null,"severity":"error","filePath":"phalcon/DataMapper/Pdo/Connection.zep","lineNumber":66,"sourceCode":"        string username = null,\n        string password = null,\n        array options = [],\n        array queries = [],\n        <ProfilerInterface> profiler = null\n    ) {\n        var parts;\n        array available;\n\n        let parts     = explode(\":\", dsn),\n            available = [\n                \"mysql\"  : true,\n                \"pgsql\"  : true,\n                \"sqlite\" : true,\n                \"mssql\"  : true\n            ];\n\n        if !isset available[parts[0]] {\n            throw new DriverNotSupported(parts[0]);\n        }\n\n\n        // if no error mode is specified, use exceptions\n        if !isset options[\\PDO::ATTR_ERRMODE] {\n            let options[\\PDO::ATTR_ERRMODE] = \\PDO::ERRMODE_EXCEPTION;\n        }\n\n        // Arguments store\n        let this->arguments = [\n            dsn,\n            username,\n            password,\n            options,\n            queries\n        ];\n\n        // Create a new profiler if none has been passed","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/DataMapper/Pdo/Connection.zep#L48-L84","documentation":"Connection's constructor splits the DSN at the first colon and requires the prefix to be one of a hardcoded whitelist — mysql, pgsql, sqlite, mssql — checked before PDO is ever constructed. Any other prefix throws DriverNotSupported, even when the installed PDO supports it (sqlsrv, dblib, oci are all rejected here).","triggerScenarios":"new Connection('sqlsrv:Server=host;Database=x', ...) or 'dblib:...' for SQL Server; 'oci:...' for Oracle; a DSN with a typo'd prefix ('mysl:'); a DSN missing the colon so the whole string becomes the prefix.","commonSituations":"SQL Server deployments (pdo_sqlsrv/pdo_dblib) or Oracle deployments where the real PDO driver name is not in the whitelist; DSNs assembled from config where the driver key is empty or user-edited.","solutions":["Use a whitelisted prefix (mysql, pgsql, sqlite, mssql) — for SQL Server over dblib the expected key here is 'mssql'","For other drivers, construct \\PDO yourself and wrap it with Connection\\Decorated, which skips the DSN check","Extend Connection and override the whitelist if you must support sqlsrv/oci natively","Validate the DSN prefix in your config layer at boot so it fails with a clear message before any connection attempt"],"exampleFix":"// before\n$conn = new Connection('sqlsrv:Server=db;Database=x', 'user', 'pass'); // DriverNotSupported\n\n// after\n$pdo = new \\PDO('sqlsrv:Server=db;Database=x', 'user', 'pass');\n$conn = new \\Phalcon\\DataMapper\\Pdo\\Connection\\Decorated($pdo);","handlingStrategy":"validation","validationCode":"const SUPPORTED_DSN_PREFIXES = ['mysql', 'pgsql', 'sqlite', 'mssql'];\n\n$prefix = strtolower(explode(':', $dsn, 2)[0]);\nif (!in_array($prefix, SUPPORTED_DSN_PREFIXES, true)) {\n    throw new InvalidArgumentException(\n        \"DSN driver '{$prefix}' is not supported by Connection; supported: \"\n        . implode(', ', SUPPORTED_DSN_PREFIXES)\n    );\n}\nreturn new Connection($dsn, $username, $password, $options);","typeGuard":null,"tryCatchPattern":"use Phalcon\\DataMapper\\Pdo\\Exception\\DriverNotSupported;\n\ntry {\n    $connection = new Connection($dsn, $username, $password);\n} catch (DriverNotSupported $e) {\n    $pdo = new \\PDO($dsn, $username, $password);\n    $connection = new \\Phalcon\\DataMapper\\Pdo\\Connection\\Decorated($pdo);\n}","preventionTips":["Normalize and validate DSN prefixes in your config layer before constructing Connection","Remember the whitelist is mysql/pgsql/sqlite/mssql even if your PDO build supports more drivers","For exotic drivers, plan on Decorated-wrapping your own \\PDO from the start"],"tags":["pdo","database","dsn","driver-not-supported","phalcon"],"backgroundTag":"unsupported-database-driver","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}