数据库：入门

简介
- 配置
- 读写连接
运行 SQL 查询
数据库事务
连接到数据库 CLI
检查数据库
监控数据库

简介

几乎每个现代 Web 应用程序都与数据库交互。Laravel 使用原始 SQL、流畅查询构建器和 Eloquent ORM，使跨各种支持的数据库与数据库交互变得极其简单。目前，Laravel 为五种数据库提供一流支持：

MariaDB 10.3+ (版本策略)
MySQL 5.7+ (版本策略)
PostgreSQL 10.0+ (版本策略)
SQLite 3.26.0+
SQL Server 2017+ (版本策略)

此外，MongoDB 通过 mongodb/laravel-mongodb 包支持，该包由 MongoDB 官方维护。查看 Laravel MongoDB 文档以获取更多信息。

配置

Laravel 数据库服务的配置位于应用程序的 config/database.php 配置文件中。在此文件中，您可以定义所有数据库连接，以及指定默认情况下应使用哪个连接。此文件中的大多数配置选项由应用程序环境变量的值驱动。此文件中提供了 Laravel 支持的大多数数据库系统的示例。

默认情况下，Laravel 的示例环境配置已准备好与 Laravel Sail 一起使用，这是一个用于在本地机器上开发 Laravel 应用程序的 Docker 配置。但是，您可以根据本地数据库的需要自由修改数据库配置。

SQLite 配置

SQLite 数据库包含在文件系统上的单个文件中。您可以在终端中使用 touch 命令创建新的 SQLite 数据库：touch database/database.sqlite。创建数据库后，您可以通过将数据库的绝对路径放在 DB_DATABASE 环境变量中，轻松配置环境变量以指向此数据库：

ini

DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/database.sqlite

默认情况下，SQLite 连接启用外键约束。如果要禁用它们，应将 DB_FOREIGN_KEYS 环境变量设置为 false：

ini

DB_FOREIGN_KEYS=false

NOTE

如果您使用 Laravel 安装程序创建 Laravel 应用程序并选择 SQLite 作为数据库，Laravel 将自动创建 database/database.sqlite 文件并为您运行默认的数据库迁移。

Microsoft SQL Server 配置

要使用 Microsoft SQL Server 数据库，应确保已安装 sqlsrv 和 pdo_sqlsrv PHP 扩展以及它们可能需要的任何依赖项，如 Microsoft SQL ODBC 驱动程序。

使用 URL 配置

通常，数据库连接使用多个配置值（如 host、database、username、password 等）进行配置。每个配置值都有自己对应的环境变量。这意味着在生产服务器上配置数据库连接信息时，需要管理多个环境变量。

一些托管数据库提供商（如 AWS 和 Heroku）提供单个数据库"URL"，其中包含单个字符串中数据库的所有连接信息。示例数据库 URL 可能如下所示：

html

mysql://root:password@127.0.0.1/forge?charset=UTF-8

这些 URL 通常遵循标准模式约定：

html

driver://username:password@host:port/database?options

为方便起见，Laravel 支持这些 URL 作为使用多个配置选项配置数据库的替代方法。如果存在 url（或相应的 DB_URL 环境变量）配置选项，它将用于提取数据库连接和凭据信息。

读写连接

有时您可能希望对 SELECT 语句使用一个数据库连接，对 INSERT、UPDATE 和 DELETE 语句使用另一个数据库连接。Laravel 使这变得轻而易举，无论您使用原始查询、查询构建器还是 Eloquent ORM，都将始终使用正确的连接。

要了解如何配置读/写连接，让我们看这个例子：

php

'mysql' => [
    'driver' => 'mysql',
    
    'read' => [
        'host' => [
            '192.168.1.1',
            '196.168.1.2',
        ],
    ],
    'write' => [
        'host' => [
            '192.168.1.3',
        ],
    ],
    'sticky' => true,
    
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'laravel'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
    'unix_socket' => env('DB_SOCKET', ''),
    'charset' => env('DB_CHARSET', 'utf8mb4'),
    'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),
    'prefix' => '',
    'prefix_indexes' => true,
    'strict' => true,
    'engine' => null,
    'options' => extension_loaded('pdo_mysql') ? array_filter([
        (PHP_VERSION_ID >= 80500 ? \Pdo\Mysql::ATTR_SSL_CA : \PDO::MYSQL_ATTR_SSL_CA) => env('MYSQL_ATTR_SSL_CA'),
    ]) : [],
],

请注意，配置数组中添加了三个键：read、write 和 sticky。read 和 write 键具有包含单个键 host 的数组值。read 和 write 连接的其余数据库选项将从主 mysql 配置数组合并。

只有在希望覆盖主 mysql 数组中的值时，才需要将项目放在 read 和 write 数组中。因此，在这种情况下，192.168.1.1 将用作"读"连接的主机，而 192.168.1.3 将用于"写"连接。数据库凭据、前缀、字符集和主 mysql 数组中的所有其他选项将在两个连接之间共享。当 host 配置数组中存在多个值时，将为每个请求随机选择数据库主机。

`sticky` 选项

sticky 选项是一个可选值，可用于允许立即读取在当前请求周期中写入数据库的记录。如果启用了 sticky 选项，并且在当前请求周期中对数据库执行了"写"操作，则任何进一步的"读"操作都将使用"写"连接。这确保在请求周期中写入的任何数据都可以在同一请求期间立即从数据库读回。由您决定这是否是应用程序所需的行为。

运行 SQL 查询

配置数据库连接后，可以使用 DB 门面运行查询。DB 门面为每种类型的查询提供方法：select、update、insert、delete 和 statement。

运行 Select 查询

要运行基本的 SELECT 查询，可以使用 DB 门面上的 select 方法：

php

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * 显示应用程序所有用户的列表。
     */
    public function index(): View
    {
        $users = DB::select('select * from users where active = ?', [1]);

        return view('user.index', ['users' => $users]);
    }
}

传递给 select 方法的第一个参数是 SQL 查询，第二个参数是需要绑定到查询的任何参数绑定。通常，这些是 where 子句约束的值。参数绑定提供对 SQL 注入的保护。

select 方法将始终返回结果 array。数组中的每个结果将是表示数据库记录的 PHP stdClass 对象：

php

use Illuminate\Support\Facades\DB;

$users = DB::select('select * from users');

foreach ($users as $user) {
    echo $user->name;
}

选择标量值

有时数据库查询可能返回单个标量值。Laravel 允许您使用 scalar 方法直接检索此值，而不需要从记录对象中检索查询的标量结果：

php

$burgers = DB::scalar(
    "select count(case when food = 'burger' then 1 end) as burgers from menu"
);

选择多个结果集

如果您的应用程序调用返回多个结果集的存储过程，可以使用 selectResultSets 方法检索存储过程返回的所有结果集：

php

[$options, $notifications] = DB::selectResultSets(
    "CALL get_user_options_and_notifications(?)", $request->user()->id
);

使用命名绑定

除了使用 ? 表示参数绑定外，还可以使用命名绑定执行查询：

php

$results = DB::select('select * from users where id = :id', ['id' => 1]);

运行 Insert 语句

要执行 insert 语句，可以使用 DB 门面上的 insert 方法。与 select 一样，此方法接受 SQL 查询作为第一个参数，绑定作为第二个参数：

php

use Illuminate\Support\Facades\DB;

DB::insert('insert into users (id, name) values (?, ?)', [1, 'Marc']);

运行 Update 语句

update 方法应用于更新数据库中的现有记录。该方法返回受语句影响的行数：

php

use Illuminate\Support\Facades\DB;

$affected = DB::update(
    'update users set votes = 100 where name = ?',
    ['Anita']
);

运行 Delete 语句

delete 方法应用于从数据库中删除记录。与 update 一样，该方法将返回受影响的行数：

php

use Illuminate\Support\Facades\DB;

$deleted = DB::delete('delete from users');

运行通用语句

某些数据库语句不返回任何值。对于这些类型的操作，可以使用 DB 门面上的 statement 方法：

php

DB::statement('drop table users');

运行未准备语句

有时您可能希望在不绑定任何值的情况下执行 SQL 语句。可以使用 DB 门面的 unprepared 方法来实现：

php

DB::unprepared('update users set votes = 100 where name = "Dries"');

WARNING

由于未准备语句不绑定参数，它们可能容易受到 SQL 注入攻击。您永远不应在未准备语句中允许用户控制的值。

隐式提交

在事务中使用 DB 门面的 statement 和 unprepared 方法时，必须小心避免导致隐式提交的语句。这些语句将导致数据库引擎间接提交整个事务，使 Laravel 无法感知数据库的事务级别。此类语句的一个示例是创建数据库表：

php

DB::unprepared('create table a (col varchar(1) null)');

请参阅 MySQL 手册以获取触发隐式提交的所有语句列表。

使用多个数据库连接

如果应用程序在 config/database.php 配置文件中定义了多个连接，可以通过 DB 门面提供的 connection 方法访问每个连接。传递给 connection 方法的连接名称应对应于 config/database.php 配置文件中列出的连接之一，或使用 config 辅助函数在运行时配置的连接：

php

use Illuminate\Support\Facades\DB;

$users = DB::connection('sqlite')->select(/* ... */);

可以使用连接实例上的 getPdo 方法访问连接的原始底层 PDO 实例：

php

$pdo = DB::connection()->getPdo();

监听查询事件

如果希望为应用程序执行的每个 SQL 查询指定一个调用的闭包，可以使用 DB 门面的 listen 方法。此方法对于记录查询或调试很有用。可以在服务提供者的 boot 方法中注册查询监听器闭包：

php

<?php

namespace App\Providers;

use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 注册任何应用程序服务。
     */
    public function register(): void
    {
        // ...
    }

    /**
     * 引导任何应用程序服务。
     */
    public function boot(): void
    {
        DB::listen(function (QueryExecuted $query) {
            // $query->sql;
            // $query->bindings;
            // $query->time;
            // $query->toRawSql();
        });
    }
}

监控累积查询时间

现代 Web 应用程序的一个常见性能瓶颈是它们查询数据库所花费的时间。幸运的是，当 Laravel 在单个请求期间花费太多时间查询数据库时，它可以调用您选择的闭包或回调。首先，向 whenQueryingForLongerThan 方法提供查询时间阈值（以毫秒为单位）和闭包。可以在服务提供者的 boot 方法中调用此方法：

php

<?php

namespace App\Providers;

use Illuminate\Database\Connection;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\ServiceProvider;
use Illuminate\Database\Events\QueryExecuted;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 注册任何应用程序服务。
     */
    public function register(): void
    {
        // ...
    }

    /**
     * 引导任何应用程序服务。
     */
    public function boot(): void
    {
        DB::whenQueryingForLongerThan(500, function (Connection $connection, QueryExecuted $event) {
            // 通知开发团队...
        });
    }
}

数据库事务

可以使用 DB 门面提供的 transaction 方法在数据库事务内运行一组操作。如果在事务闭包内抛出异常，事务将自动回滚并重新抛出异常。如果闭包成功执行，事务将自动提交。使用 transaction 方法时无需担心手动回滚或提交：

php

use Illuminate\Support\Facades\DB;

DB::transaction(function () {
    DB::update('update users set votes = 1');

    DB::delete('delete from posts');
});

处理死锁

transaction 方法接受一个可选的第二个参数，该参数定义在发生死锁时应重试事务的次数。一旦这些尝试耗尽，将抛出异常：

php

use Illuminate\Support\Facades\DB;

DB::transaction(function () {
    DB::update('update users set votes = 1');

    DB::delete('delete from posts');
}, attempts: 5);

手动使用事务

如果您希望手动开始事务并完全控制回滚和提交，可以使用 DB 门面提供的 beginTransaction 方法：

php

use Illuminate\Support\Facades\DB;

DB::beginTransaction();

可以通过 rollBack 方法回滚事务：

php

DB::rollBack();

最后，可以通过 commit 方法提交事务：

php

DB::commit();

NOTE

DB 门面的事务方法控制查询构建器和 Eloquent ORM 的事务。

连接到数据库 CLI

如果您希望连接到数据库的 CLI，可以使用 db Artisan 命令：

shell

php artisan db

如果需要，可以指定数据库连接名称以连接到非默认连接的数据库连接：

shell

php artisan db mysql

检查数据库

使用 db:show 和 db:table Artisan 命令，您可以获得有关数据库及其关联表的宝贵见解。要查看数据库概览，包括其大小、类型、打开连接数和表摘要，可以使用 db:show 命令：

shell

php artisan db:show

可以通过 --database 选项向命令提供数据库连接名称来指定应检查的数据库连接：

shell

php artisan db:show --database=pgsql

如果希望在命令输出中包含表行数和数据库视图详细信息，可以分别提供 --counts 和 --views 选项。在大型数据库上，检索行数和视图详细信息可能很慢：

shell

php artisan db:show --counts --views

此外，可以使用以下 Schema 方法检查数据库：

php

use Illuminate\Support\Facades\Schema;

$tables = Schema::getTables();
$views = Schema::getViews();
$columns = Schema::getColumns('users');
$indexes = Schema::getIndexes('users');
$foreignKeys = Schema::getForeignKeys('users');

如果希望检查不是应用程序默认连接的数据库连接，可以使用 connection 方法：

php

$columns = Schema::connection('sqlite')->getColumns('users');

表概览

如果希望获取数据库中单个表的概览，可以执行 db:table Artisan 命令。此命令提供数据库表的一般概览，包括其列、类型、属性、键和索引：

shell

php artisan db:table users

监控数据库

使用 db:monitor Artisan 命令，您可以指示 Laravel 在数据库管理超过指定数量的打开连接时调度 Illuminate\Database\Events\DatabaseBusy 事件。

数据库：入门 ​

简介 ​

配置 ​

SQLite 配置 ​

Microsoft SQL Server 配置 ​

使用 URL 配置 ​

读写连接 ​

sticky 选项 ​

运行 SQL 查询 ​

运行 Select 查询 ​

选择标量值 ​

选择多个结果集 ​

使用命名绑定 ​

运行 Insert 语句 ​

运行 Update 语句 ​

运行 Delete 语句 ​

运行通用语句 ​

运行未准备语句 ​

隐式提交 ​

使用多个数据库连接 ​

监听查询事件 ​

监控累积查询时间 ​

数据库事务 ​

处理死锁 ​

手动使用事务 ​

连接到数据库 CLI ​

检查数据库 ​

表概览 ​

监控数据库 ​

数据库：入门

简介

配置

SQLite 配置

Microsoft SQL Server 配置

使用 URL 配置

读写连接

`sticky` 选项

运行 SQL 查询

运行 Select 查询

选择标量值

选择多个结果集

使用命名绑定

运行 Insert 语句

运行 Update 语句

运行 Delete 语句

运行通用语句

运行未准备语句

隐式提交

使用多个数据库连接

监听查询事件

监控累积查询时间

数据库事务

处理死锁

手动使用事务

连接到数据库 CLI

检查数据库

表概览

监控数据库