Database Configuration

Previous Next

Before any of the ORM calls from the previous page can actually reach a database, CakePHP needs to know how to connect to one — host, username, password, and which database to use. That connection information lives in a specific configuration file, deliberately kept separate from the rest of your app's config.

app.php vs. app_local.php

File	Purpose	Committed to version control?
`config/app.php`	Default structure and non-secret settings, shared with every developer	Yes
`config/app_local.php`	Real, environment-specific values — including database credentials	No — gitignored by default

CakePHP loads app.php first and then merges app_local.php on top of it, so any value you set in app_local.php overrides the corresponding value in app.php. The database connection details specifically belong in app_local.php.

The Datasources.default Array

Inside app_local.php, the connection is described as an array under Datasources.default. The main keys you'll set are the database host, username, password, database name, and the driver class for your database engine.

<?php
return [
    'Datasources' => [
        'default' => [
            'host' => 'localhost',
            'username' => 'my_app',
            'password' => 'super-secret-password',
            'database' => 'my_app',
            'driver' => Cake\Database\Driver\Mysql::class,
        ],
    ],
];

host, username, and password are your MySQL server's connection details, database is the schema name to connect to, and driver tells CakePHP which database engine's SQL dialect to speak — Cake\Database\Driver\Mysql for MySQL, with similar driver classes available for Postgres and SQLite.

Why Credentials Belong in app_local.php

This split exists for the same reason covered on Core PHP's Security page: real credentials should never end up committed to version control, where they'd be visible to anyone with repository access — including in the project's full history, even if removed later. Since app_local.php is gitignored by default, every developer (and every environment — local, staging, production) can keep their own copy with their own real values, while app.php stays generic and safe to share.

Note: A common pattern is to commit a config/app_local.example.php file with placeholder values, so new developers know exactly which keys they need to fill in without ever seeing real credentials.

Testing the Connection

There's no special "test connection" command needed for a quick check — simply load any page in your app that queries the database, such as the Articles index page from the Views & Layouts page. If the credentials are wrong or the database is unreachable, CakePHP throws a clear connection error naming the problem; if the page renders your data instead, the connection is working.

Next steps: With a working database connection in place, head to CRUD Operations to actually create, read, update, and delete records through the ORM.

Previous Next