資料庫設定

簡介

Laravel 官方支援下列資料庫：

MySQL / MariaDB
PostgreSQL
SQLite
SQL Server

無論你使用原生 SQL、Query Builder 或 Eloquent ORM，都可以共用相同的連線設定。

本頁著重於資料庫連線的前提。實務查詢請參閱 Query Builder，Schema 管理請見 Migrations，資料初始化請見 Seeding。

設定

資料庫設定集中在 config/database.php。你可以在 default 選擇預設連線名稱，並在 connections 中定義各連線的細節。

// config/database.php
'default' => env('DB_CONNECTION', 'sqlite'),

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

.env 至少設定以下項目：

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=app
DB_USERNAME=app_user
DB_PASSWORD=secret

若使用 SQLite，請設定 DB_CONNECTION=sqlite 與 DB_DATABASE 的檔案路徑。

讀寫連線分離

若要將讀取（SELECT）與寫入（INSERT / UPDATE / DELETE）分別放到不同主機，可在同一連線內設定 read 與 write。

'mysql' => [
    'driver' => 'mysql',
    'read' => [
        'host' => ['10.0.0.10', '10.0.0.11'],
    ],
    'write' => [
        'host' => ['10.0.0.20'],
    ],
    'sticky' => true,

    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'laravel'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
],

將 sticky 設為 true 時，同一次請求內於寫入後的讀取都會固定到 write 連線。

若有 replica 延遲，啟用 sticky 可以降低寫入後立刻讀到舊資料的風險。

在後續請求中也防止讀到舊資料

sticky 只在同一次請求內有效。若希望在同一個 session 的後續請求中也能讀到剛寫入的資料，請將 PreventStaleDatabaseReads middleware 加入 web middleware group。

use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Foundation\Http\Middleware\PreventStaleDatabaseReads;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(append: [
        PreventStaleDatabaseReads::class,
    ]);
})

此 middleware 會將對預設資料庫連線的寫入記錄到 session 中。預設情況下，寫入後 2 秒內的請求會使用 write 連線來讀取該連線。若要變更時間長度，請指定 for。

$middleware->web(append: [
    PreventStaleDatabaseReads::for(5),
]);

由於此 middleware 依賴 session，必須在 StartSession middleware 之後執行。它不會影響其他 session 或其他資料庫連線的讀取。

暫時使用 write 連線讀取

若要將回呼內的讀取固定到 write 連線，請使用連線的 usingWritePdo。

use Illuminate\Support\Facades\DB;

$users = DB::connection()->usingWritePdo(
    fn ($connection) => $connection->table('users')->get(),
);

這同樣適用於在回呼內使用相同連線的 Eloquent 與 relationship 查詢。回呼結束時，無論是否發生例外，連線的讀取設定都會恢復原狀。

Pooled PostgreSQL 連線

當你使用如 PgBouncer 等提供交易模式連線池的託管 PostgreSQL 服務時，可以設定 pooled 與 direct 選項。

'pgsql' => [
    'driver' => 'pgsql',
    // ...
    'pooled' => env('DB_POOLED', false),
    'direct' => array_filter([
        'host' => env('DB_DIRECT_HOST'),
        'port' => env('DB_DIRECT_PORT'),
        'username' => env('DB_DIRECT_USERNAME'),
        'password' => env('DB_DIRECT_PASSWORD'),
        'sslmode' => env('DB_DIRECT_SSLMODE'),
    ]),
],

啟用 pooled 後，Laravel 會自動分派：

操作	使用的連線
應用程式查詢	pooled（會自動啟用 emulated prepared）
Migration / `db:wipe` / `db:show` / `db:table`	direct（自動）
`php artisan db`	direct（預設）；加 `--pooled` 切至 pooled

若想在應用程式碼中明確使用 direct 連線，可在連線名稱後加上 ::direct 後綴。

DB::connection('pgsql::direct')->statement('create extension if not exists "uuid-ossp"');

多重資料庫連線

你可以在 config/database.php 定義多個連線，並透過 DB::connection() 切換。

use Illuminate\Support\Facades\DB;

$users = DB::connection('sqlite')->select('select * from users');
$pdo = DB::connection('pgsql')->getPdo();

執行 SQL 查詢

DB Facade 依照查詢類型提供對應的方法。

use Illuminate\Support\Facades\DB;

$users = DB::select('select * from users where active = ?', [1]);

DB::insert('insert into users (name, email) values (?, ?)', ['Taylor', '[email protected]']);

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

$deleted = DB::delete('delete from sessions where user_id = ?', [1]);

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

切勿將使用者輸入直接串接到 SQL 字串中。務必使用參數繫結以防止 SQL injection。

查詢監聽

若想追蹤已執行的 SQL，可在 Service Provider 的 boot() 中註冊 DB::listen()。

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

public function boot(): void
{
    DB::listen(function (QueryExecuted $query) {
        logger()->debug('SQL executed', [
            'sql' => $query->toRawSql(),
            'time_ms' => $query->time,
        ]);
    });
}

Transaction

若要把多個更新視為一個單元，可使用 DB::transaction()。發生例外時 Laravel 會自動 rollback。

use Illuminate\Support\Facades\DB;

DB::transaction(function () {
    DB::update('update users set votes = 1');
    DB::delete('delete from posts where archived = 1');
});

若需要死鎖重試，可以指定 attempts。

DB::transaction(function () {
    // ...
}, attempts: 5);

若想手動控制，可使用 beginTransaction / rollBack / commit。

DB::beginTransaction();

try {
    DB::update('update accounts set balance = balance - 100 where id = ?', [1]);
    DB::update('update accounts set balance = balance + 100 where id = ?', [2]);

    DB::commit();
} catch (\Throwable $e) {
    DB::rollBack();
    throw $e;
}

下一步

Query Builder

學習如何在連線設定之上安全地組建查詢。

Migrations

學習如何對已連線的資料庫 schema 進行版本控管。

Seeding

學習如何以可重現的方式匯入開發 / 測試用資料。

架構

資料庫

Eloquent

安全性

事件

郵件與通知

付款

非同步處理

即時通訊

排程

快取與最佳化

國際化

檔案與儲存

偵錯與監控

主控台與 CLI

效能

前端

AI 開發

開發環境

簡介

設定

讀寫連線分離

在後續請求中也防止讀到舊資料

暫時使用 write 連線讀取

Pooled PostgreSQL 連線

多重資料庫連線

執行 SQL 查詢

查詢監聽

Transaction

下一步

Query Builder

Migrations

Seeding

​簡介

​設定

​讀寫連線分離

​在後續請求中也防止讀到舊資料

​暫時使用 write 連線讀取

​Pooled PostgreSQL 連線

​多重資料庫連線

​執行 SQL 查詢

​查詢監聽

​Transaction

​下一步

Query Builder

Migrations

Seeding

簡介

設定

讀寫連線分離

在後續請求中也防止讀到舊資料

暫時使用 write 連線讀取

Pooled PostgreSQL 連線

多重資料庫連線

執行 SQL 查詢

查詢監聽

Transaction

下一步