Comprehensive Guide to MySQL Database Connection Configuration in Laravel: From Basic Setup to Environment Variables Management

In Laravel development, database connection configuration is a fundamental yet critical aspect. Many developers, especially those new to Laravel, frequently encounter database connection failures, often due to improper configuration or insufficient understanding of Laravel's configuration mechanisms. This article analyzes a typical error case to explore MySQL database connection configuration methods in Laravel and provides detailed solutions.

Default Configuration and Common Error Analysis

After installation, Laravel provides a default database configuration file at app/config/database.php. The default MySQL connection configuration in this file is as follows:

'mysql' => array(
    'driver'    => 'mysql',
    'host'      => 'localhost',
    'database'  => 'database',
    'username'  => 'root',
    'password'  => '',
    'charset'   => 'utf8',
    'collation' => 'utf8_unicode_ci',
    'prefix'    => '',
),

The key issue here is the line 'database' => 'database'. Laravel by default expects to connect to a database named "database". If developers haven't created a database with this name in MySQL, executing database operations like php artisan migrate will result in the error SQLSTATE[HY000] [1049] Unknown database 'database'.

Solution 1: Modifying the database.php Configuration File

The most straightforward solution is to modify the database name in the database.php file to match the actual database name. For example, if your database is named "my_awesome_data", the configuration should be updated to:

'mysql' => array(
    'driver'    => 'mysql',
    'host'      => 'localhost',
    'database'  => 'my_awesome_data',
    'username'  => 'root',
    'password'  => '',
    'charset'   => 'utf8',
    'collation' => 'utf8_unicode_ci',
    'prefix'    => '',
),

After making these changes, ensure the following:

1. MySQL service is running
2. The specified database exists (if not, create it via phpMyAdmin or MySQL command line first)
3. Username and password are correct (by default, WAMP's MySQL username is "root" with an empty password)

Solution 2: Using the .env Environment Variables File

In Laravel 5 and later versions, it's recommended to use the environment variables file .env to manage database configuration. This approach offers better security and flexibility, especially when switching between different environments (development, testing, production).

First, check if the .env file exists in the project root directory. If not, copy it from .env.example:

cp .env.example .env

Then edit the .env file to modify database-related configurations:

DB_HOST=localhost
DB_DATABASE=my_awesome_data
DB_USERNAME=root
DB_PASSWORD=

In the database.php file, Laravel automatically reads these environment variables:

'mysql' => array(
    'driver'    => 'mysql',
    'host'      => env('DB_HOST', 'localhost'),
    'database'  => env('DB_DATABASE', 'database'),
    'username'  => env('DB_USERNAME', 'root'),
    'password'  => env('DB_PASSWORD', ''),
    'charset'   => 'utf8',
    'collation' => 'utf8_unicode_ci',
    'prefix'    => '',
),

The env() function here prioritizes values from the .env file, using the second parameter as the default if not found.

Configuration Priority and Best Practices

Understanding configuration priority in Laravel is essential to avoid conflicts:

1. Configurations in the .env file have the highest priority
2. If no relevant configuration exists in .env, defaults from database.php are used
3. Environment variables can be easily switched between different deployment environments without code modifications

In practical development, the following best practices are recommended:

1. Never commit the .env file to version control (ensure it's in .gitignore)
2. Create separate .env files for each environment (e.g., .env.local, .env.production)
3. Use strong passwords instead of empty ones, especially in production environments
4. Regularly back up database configuration files

Troubleshooting Common Issues

If database connection issues persist after following the above steps, try these troubleshooting methods:

1. Verify that the MySQL service is running properly
2. Confirm that the database name, username, and password are correct
3. Ensure the database user has sufficient permissions
4. Check firewall settings to ensure port 3306 (MySQL default port) is open
5. Examine Laravel's log file storage/logs/laravel.log for more detailed error information

By correctly configuring database connections, developers can fully leverage Laravel's powerful database features, including Eloquent ORM, database migrations, and seeding, leading to more efficient web application development.