資料庫設定

說明 Laravel 的資料庫連線設定、read/write 分離、多重連線、SQL 執行、查詢監聽與 transaction 的基本概念。

​

簡介

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 可以降低寫入後立刻讀到舊資料的風險。

​

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', '[e-mail]']);

$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

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