Laravel 11 数据库连接配置

几乎所有的 Web 应用都需要与数据库交互。Laravel 提供了简洁而强大的数据库配置方式，支持 MySQL、PostgreSQL、SQLite、SQL Server 等多种数据库。本章将带你完成数据库连接的配置，确保应用能够顺利连接并使用数据库。

📁 配置文件概览

Laravel 的数据库配置主要涉及两个文件：

.env —— 环境变量文件，存放与本地环境相关的敏感信息（如数据库密码）。
config/database.php —— 配置文件，定义所有数据库连接的详细参数，并引用环境变量。

这种分离设计使得开发、测试、生产环境可以拥有独立的配置，且敏感信息不会被提交到版本控制系统。

⚙️ 环境变量配置（.env）

在项目根目录的 .env 文件中，你可以看到数据库相关的默认配置：

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

各参数含义：

DB_CONNECTION —— 使用的数据库类型（如 mysql、pgsql、sqlite、sqlsrv）。
DB_HOST —— 数据库服务器地址。
DB_PORT —— 端口号（默认 MySQL 3306，PostgreSQL 5432）。
DB_DATABASE —— 数据库名称。
DB_USERNAME —— 数据库用户名。
DB_PASSWORD —— 数据库密码。

💡 提示： 如果你使用 SQLite，只需将 DB_CONNECTION=sqlite 并设置 DB_DATABASE 为数据库文件的绝对路径（如 /absolute/path/to/database.sqlite），其他字段可以留空。

📝 配置文件详解（config/database.php）

config/database.php 中定义了所有支持的数据库连接。Laravel 11 默认配置如下：

'default' => env('DB_CONNECTION', 'mysql'),

'connections' => [
    'sqlite' => [
        'driver' => 'sqlite',
        'url' => env('DATABASE_URL'),
        'database' => env('DB_DATABASE', database_path('database.sqlite')),
        'prefix' => '',
        'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
    ],

    'mysql' => [
        'driver' => 'mysql',
        'url' => env('DATABASE_URL'),
        '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', ''),
        'unix_socket' => env('DB_SOCKET', ''),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => '',
        'prefix_indexes' => true,
        'strict' => true,
        'engine' => null,
        'options' => extension_loaded('pdo_mysql') ? array_filter([
            PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
        ]) : [],
    ],

    'pgsql' => [
        'driver' => 'pgsql',
        'url' => env('DATABASE_URL'),
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', '5432'),
        'database' => env('DB_DATABASE', 'forge'),
        'username' => env('DB_USERNAME', 'forge'),
        'password' => env('DB_PASSWORD', ''),
        'charset' => 'utf8',
        'prefix' => '',
        'prefix_indexes' => true,
        'search_path' => 'public',
        'sslmode' => 'prefer',
    ],

    // ... 其他数据库配置
],

关键点：

default 指定默认使用的连接名称，通过 DB_CONNECTION 环境变量覆盖。
connections 数组定义了多个数据库连接，你可以根据需要添加自定义连接（如用于读写的分离）。
每个连接都有 driver、host、database、username、password 等参数，大部分都从环境变量读取。
charset、collation、prefix 等用于控制字符集和表前缀。

🔌 配置不同数据库类型

1. MySQL / MariaDB

通常只需修改 .env 中的对应项，并确保数据库服务已启动。常见额外配置：

// 在 config/database.php 的 mysql 连接中添加
'options' => [
    PDO::ATTR_PERSISTENT => true,  // 持久连接
    PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'), // SSL 证书
],

2. PostgreSQL

设置 .env 中的 DB_CONNECTION=pgsql，并填写正确的 DB_HOST、DB_PORT 等。如果需要指定 schema，可在 search_path 中配置：

'search_path' => 'public',  // 多个 schema 用逗号分隔，如 'public, tenant'

3. SQLite

SQLite 是轻量级文件数据库，非常适合开发和测试。配置步骤：

创建数据库文件：touch database/database.sqlite（或任意路径）
在 .env 中设置：DB_CONNECTION=sqlite 和 DB_DATABASE=/absolute/path/to/database.sqlite
如需使用内存数据库（测试），可将 DB_DATABASE 设为 :memory:。

💡 提示： Laravel 11 中 SQLite 默认开启了外键约束（foreign_key_constraints），若需关闭可设为 false。

4. SQL Server (sqlsrv)

配置示例：

'sqlsrv' => [
    'driver' => 'sqlsrv',
    'url' => env('DATABASE_URL'),
    'host' => env('DB_HOST', 'localhost'),
    'port' => env('DB_PORT', '1433'),
    'database' => env('DB_DATABASE', 'forge'),
    'username' => env('DB_USERNAME', 'forge'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8',
    'prefix' => '',
    'prefix_indexes' => true,
    // 'encrypt' => env('DB_ENCRYPT', 'yes'),
    // 'trust_server_certificate' => env('DB_TRUST_SERVER_CERTIFICATE', 'false'),
],

🔁 多数据库连接

如果你的应用需要连接多个数据库，可以在 connections 中添加新的连接，然后通过 DB::connection('name') 来使用。

示例：在 .env 中定义第二个数据库的配置：

DB_CONNECTION_SECONDARY=mysql
DB_HOST_SECONDARY=192.168.1.100
DB_PORT_SECONDARY=3306
DB_DATABASE_SECONDARY=secondary_db
DB_USERNAME_SECONDARY=user2
DB_PASSWORD_SECONDARY=pass2

然后在 config/database.php 中添加连接：

'connections' => [
    // ... 默认连接
    'secondary' => [
        'driver' => env('DB_CONNECTION_SECONDARY', 'mysql'),
        'host' => env('DB_HOST_SECONDARY', '127.0.0.1'),
        'port' => env('DB_PORT_SECONDARY', '3306'),
        'database' => env('DB_DATABASE_SECONDARY', 'forge'),
        'username' => env('DB_USERNAME_SECONDARY', 'forge'),
        'password' => env('DB_PASSWORD_SECONDARY', ''),
        // ... 其他选项
    ],
],

使用时：$users = DB::connection('secondary')->table('users')->get();。

✅ 测试数据库连接

配置完成后，可以通过 Artisan 命令或代码来测试连接是否成功。

Artisan 命令

php artisan db:show

该命令会显示默认数据库的信息，包括表数量、大小等。若连接失败，会抛出异常。

代码测试

在 Tinker 或临时路由中运行：

use Illuminate\Support\Facades\DB;

Route::get('/test-db', function () {
    try {
        DB::connection()->getPdo();
        echo "连接成功！数据库：".DB::connection()->getDatabaseName();
    } catch (\Exception $e) {
        die("连接失败：" . $e->getMessage());
    }
});

⚠️ 常见问题排查

检查 .env 中的 DB_USERNAME 和 DB_PASSWORD 是否正确，以及该用户是否有权限访问指定的数据库。另外，确认 MySQL 服务是否允许远程连接（如 bind-address 配置）。

需要确保 PHP 安装了 pdo_sqlite 扩展。在 Linux 中可通过 sudo apt install php8.2-sqlite3（根据 PHP 版本调整），Windows 需在 php.ini 中取消 extension=php_pdo_sqlite.dll 的注释。

确认数据库是否已创建，可以通过 createdb xxx 命令创建。另外检查 DB_DATABASE 是否正确。

首先确保 .env 文件存在且位于项目根目录。修改配置后，需要重启服务器（php artisan serve 需停止重启）或清除配置缓存：php artisan config:clear。

📝 小结

数据库连接配置是 Laravel 应用的基础。通过合理配置 .env 和 config/database.php，你可以轻松连接多种数据库，并支持多连接切换。掌握配置技巧后，下一章我们将学习查询构建器，开始与数据库进行数据交互。

上一章: 全局与路由中间件下一章: 查询构建器基础

Laravel教程