The "Database [postgres] not configured" Mystery in Laravel 5
When configuring a new Laravel 5 project with PostgreSQL, it is easy to misinterpret error messages from the database config file. A common stumbling block occurs when developers see the exception [InvalidArgumentException] Database [postgres] not configured despite having correctly defined a connection named pgsql. This confusion usually stems from how Laravel resolves the default connection and the distinction between the connection name used in the configuration array versus the value passed to the database facade.
In the scenario described, the default key in /config/database.php is set to 'postgres':
'default' => env('DB_CONNECTION', 'postgres')
This setting tells Laravel to look for a connection definition with the key postgres. However, the connections array within the same file only defines a driver with the key pgsql:
'pgsql' => [
'driver' => 'pgsql',
// ... other settings
],
The error message is literal: Laravel attempted to instantiate a connection named postgres, found no definition for that specific key, and threw an exception. The developer's assumption that the driver name (pgsql) must match the default connection key is incorrect. The keys serve different purposes. The default key represents the logical identifier you will use when calling DB::connection('default') or when referencing the connection in migrations. The keys inside the connections array are arbitrary identifiers, provided they are unique and map to a valid driver.
To resolve this, you must ensure that the string value in the default configuration key exists as a key within the connections array. There are two standard approaches to fixing this alignment issue:
Option 1: Align the Keys (Recommended)
The cleanest solution is to change the key inside the connections array from 'pgsql' to 'postgres'. This maintains consistency between your environment variables and the actual configuration keys. Update the configuration file as follows:
'default' => env('DB_CONNECTION', 'postgres'),
'connections' => [
'postgres' => [ // Changed key here
'driver' => 'pgsql',
'host' => env('DB_HOST', 'localhost'),
'database' => env('DB_DATABASE', 'example_database'),
'username' => env('DB_USERNAME', 'example_username'),
'password' => env('DB_PASSWORD', 'example_password'),
'charset' => 'utf8',
'prefix' => '',
'schema' => 'public'
],
// ... other connections
]
Now, when Laravel reads the default setting, it finds a matching key in the array, and the DB::connection() call succeeds.
Option 2: Update the Default Connection Name
Alternatively, you can keep the connection array key as 'pgsql' but update the default value to match it. This approach is less common in Laravel 5 projects but functionally valid if your team prefers using pgsql everywhere.
'default' => env('DB_CONNECTION', 'pgsql') // Changed default here
While this works, it often leads to inconsistency when referencing the connection in migrations or seeding scripts, where developers might expect the key to be 'postgres' for simplicity.
Environment Variables and Caching
It is also important to verify that your environment variables are being read correctly. If you are running Laravel 5 on a shared hosting environment like cPanel, ensure that the .env file contains the correct values:
DB_CONNECTION=pgsql
DB_HOST=localhost
DB_DATABASE=example_database
DB_USERNAME=example_username
DB_PASSWORD=example_password
In Laravel 5, configuration files are cached. If you modified /config/database.php or the .env file but still see the old error, you may need to clear the cache before migrating:
php artisan config:clear
php artisan migrate
The DB_DATABASE value in your example code was marked as "ignored" in your investigation, but it is not ignored by Laravel; it is simply that the connection key mismatch prevented the application from ever reaching the point where it would validate or use those credentials. Once the keys align, the database driver will correctly authenticate against PostgreSQL using the provided username and password.