How to set up a database connection in Laravel?

To set up a database connection in Laravel, update the .env file with correct credentials, configure settings in config/database.php, test the connection using Artisan or custom code, and resolve common issues like permissions or caching. 1. Update the .env file with DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, and DB_PASSWORD, ensuring the database exists and is accessible. 2. Configure config/database.php to map environment variables to connection settings, adjusting charset, collation, or SSL as needed. 3. Test the connection via php artisan migrate or a manual PDO check to confirm connectivity. 4. Address common pitfalls including user privileges, incorrect ports, missing PHP extensions, caching, and SQLite file permissions.

Setting up a database connection in Laravel is straightforward, especially if you're familiar with the .env file and Laravel's configuration structure. The key lies in setting the right environment variables and making sure your database server is accessible.

1. Update the .env File

Laravel uses the .env file to manage environment-specific configurations, including database settings.

You’ll typically see something like this:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password

If you’re using a different database driver like PostgreSQL or SQLite, change DB_CONNECTION accordingly (e.g., pgsql, sqlite, etc.).

Make sure:

• Your database exists (or SQLite file path is correct).
• The credentials are valid.
• The database server is running and accessible from your app.

For local development, most people use MySQL via tools like XAMPP, MAMP, or Laravel Homestead.

2. Configure Database Settings in config/database.php

While the .env file holds your actual values, Laravel reads from config/database.php for how to interpret them.

Inside this file, you’ll find an 'connections' array that includes all supported drivers. Each one looks something like:

'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'forge'),
    'username' => env('DB_USERNAME', 'forge'),
    'password' => env('DB_PASSWORD', ''),
    ...
],

You can customize things like charset, collation, and even add SSL options here if needed — just make sure they match your database setup.

If you're connecting to a remote DB, double-check firewalls and access permissions.

3. Test the Connection

Once configured, it’s always a good idea to test the connection to catch any errors early.

You can do this by running a simple Artisan command:

php artisan migrate

If there’s an issue connecting, Laravel will throw an error explaining what went wrong — usually either a credential issue, unreachable host, or incorrect port.

Alternatively, create a quick route or console command that runs:

try {
    DB::connection()->getPdo();
    echo "Connected successfully.";
} catch (\Exception $e) {
    die("Could not connect to the database. Error: " . $e->getMessage());
}

This tries to establish a PDO connection and gives a clear message if it fails.

4. Common Pitfalls and Fixes

Here are a few common issues and how to resolve them:

• Database user lacks privileges – Make sure the user has permission to access and modify the database.
• Incorrect DB port – Some setups use non-default ports (like 33070 on Docker environments).
• Missing extensions – Ensure PHP has the necessary extensions enabled (e.g., pdo_mysql).
• Caching issues – After changing .env, run php artisan config:clear or restart your server if changes don’t take effect.
• SQLite file not writable – If using SQLite, make sure the file exists and has proper permissions.

That’s basically it. It seems simple, but getting these small details right makes all the difference when connecting Laravel to your database.

The above is the detailed content of How to set up a database connection in Laravel?. For more information, please follow other related articles on the PHP Chinese website!