CakePHP Database connection "Mysql" is missing, or could not be created

CakePHP Database connection "Mysql" is missing, or could not be created

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

Stefan Bogdanescu

Founder & Senior Architect

CakePHP Database connection "Mysql" is missing, or could not be created

When a CakePHP application fails with the message Cake is NOT able to connect to the database. Database connection "Mysql" is missing, or could not be created, it typically signals one of two distinct failure modes: a configuration issue in your database.php file or a runtime error where the PDO driver cannot instantiate a connection due to environment constraints. The error message specifically references "Mysql" (case-insensitive), which maps to the legacy Database/Mysql datasource class or the modern Database/Mysql/PdoMySql depending on your CakePHP version.

A common point of confusion arises when debugging this issue using standalone scripts, such as a home.ctp file. If you run a connection test script and receive SQLSTATE[42000] [1049] Unknown database 'test', it indicates that the script is attempting to connect to a database named test rather than your configured database. This discrepancy often happens if the testing script uses default CakePHP configuration values or environment variables that override your manual settings in app/Config/database.php.

Resolving Configuration Mismatches

The primary suspect when seeing "Database connection 'Mysql' is missing" is the datasource class name defined in your configuration. In older versions of CakePHP (prior to 3.x), the legacy adapter was named Database/Mysql. In CakePHP 3 and later, the convention shifted toward PDO based adapters, specifically Database/Mysql/PdoMySql.

If you are using CakePHP 3 or higher, defining 'datasource' => 'Database/Mysql' will cause the connection manager to fail because that class no longer exists. The modern approach requires specifying the PDO driver explicitly. You should update your configuration in app/Config/database.php to reflect the current adapter hierarchy:

return [
    'default' => [
        'host' => 'localhost',
        'username' => 'Ben',
        'password' => 'mypass',
        'database' => 'CV',
        'timezone' => 'UTC',
        'encoding' => 'utf8mb4',
        'persistent' => false,
        'schema' => [
            'default' => 'CakeSchema'
        ]
    ],
];

Note that the legacy Datasources array structure is deprecated in modern CakePHP. If you are strictly maintaining a legacy application, ensure the class name matches exactly what exists in your vendor folder. The error "could not be created" implies that the framework tried to instantiate the class but failed, either because the class was missing or because the underlying PDO driver could not load.

Driver Installation and Environment Constraints

Even with correct configuration, the connection will fail if the PHP environment lacks the required PDO extensions. The Database/Mysql datasource relies on the pdo_mysql extension being enabled in php.ini. If this extension is missing, CakePHP cannot create the connection object, resulting in the generic "could not be created" error.

To verify this, check your PHP configuration:

php -m | grep pdo

If pdo_mysql is not listed, you must install the extension for your specific PHP version and OS. On many Linux distributions, this involves installing the php-mysql or php-pdo packages via the package manager. On macOS using Homebrew or MAMP (as suggested in the source scenario), ensure the PHP configuration loaded by the web server includes these extensions.

Debugging Unknown Database Errors

The specific error SQLSTATE[42000] [1049] Unknown database 'test' appearing in your diagnostic script is a critical clue. It suggests that while your main application points to the CV database, the diagnostic tool you are running is defaulting to test. This often occurs when CakePHP's internal test suite or a specific helper file initializes a connection with a different name before your custom logic runs.

Ensure that any standalone PHP files in your document root do not implicitly load CakePHP's default configuration which might point to a local development database named test. If you are using environment variables to manage connections, ensure they are set correctly for the specific host accessing the application.

The Role of Schema and Connection Management

If the configuration and drivers are correct, the "missing" connection could also stem from schema issues in Cake 3.x where the default schema is named CakeSchema but not found. Ensure your default connection is configured to load a valid schema file or that you have created the necessary tables after connecting.

In some legacy setups, the Datasources array might be misconfigured, pointing to a non-existent class. Always verify that the path to the datasource class matches the installed version of the framework. If you are migrating from an older setup, remember that Database/Mysql was replaced by Database/Mysql/PdoMySql in CakePHP 3.0. Using the old class name in a new environment will trigger the "could not be created" error immediately upon loading the application.

For developers seeking more robust database management practices or looking to migrate legacy applications to modern stacks, resources like https://laravelcompany.com offer insights into best practices for handling database migrations and connection pooling, which can help prevent similar issues in new projects by enforcing standardized configuration patterns.

Our network