Configurazione del database

Introduzione

Laravel supporta ufficialmente i seguenti database.

MySQL / MariaDB
PostgreSQL
SQLite
SQL Server

Puoi usare le stesse impostazioni di connessione sia con SQL grezzo, sia con Query Builder, sia con Eloquent ORM.

Questa pagina copre le premesse sulle connessioni al database. Per le query pratiche consulta Query Builder, per la gestione dello schema le Migration, per l’inserimento dei dati iniziali il Seeding.

Configurazione

La configurazione del database è concentrata in config/database.php. Con default scegli la connessione predefinita e con connections definisci i dettagli di ciascuna.

// 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', ''),
    ],
],

Nel .env imposta almeno quanto segue.

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

Se usi SQLite imposta DB_CONNECTION=sqlite e il percorso di DB_DATABASE.

Separazione delle connessioni di lettura e scrittura

Se vuoi separare letture (SELECT) e scritture (INSERT / UPDATE / DELETE) su host diversi, configura read e write all’interno della stessa connessione.

'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', ''),
],

Con sticky impostato a true, le letture successive a una scrittura nella stessa richiesta vengono fissate sulla connessione di scrittura.

In configurazioni con ritardo di replica, abilitare sticky riduce il rischio di leggere dati obsoleti immediatamente dopo una scrittura.

Prevenire letture obsolete anche nelle richieste successive

sticky è valido solo all’interno della stessa richiesta. Se vuoi leggere i dati appena scritti anche nelle richieste successive della stessa sessione, aggiungi il middleware PreventStaleDatabaseReads al gruppo di middleware web.

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

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

Il middleware registra nella sessione le scritture sulla connessione al database predefinita. Per impostazione predefinita, le richieste effettuate entro 2 secondi da una scrittura usano la connessione di scrittura per le letture su quella connessione. Per modificare la durata, specifica for.

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

Poiché dipende dalla sessione, questo middleware deve essere eseguito dopo il middleware StartSession. Non influisce sulle letture di altre sessioni o di altre connessioni al database.

Leggere temporaneamente dalla connessione di scrittura

Per fissare le letture all’interno di una callback sulla connessione di scrittura, usa il metodo usingWritePdo della connessione.

use Illuminate\Support\Facades\DB;

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

Vale anche per le query Eloquent e delle relationship che usano la stessa connessione all’interno della callback. Al termine della callback, l’impostazione di lettura della connessione viene ripristinata, indipendentemente dal verificarsi di un’eccezione.

Connessione PostgreSQL con pool

Quando usi un servizio PostgreSQL gestito che offre connection pooling in modalità transaction (come PgBouncer), configura le opzioni pooled e 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'),
    ]),
],

Abilitando pooled, Laravel effettua automaticamente lo smistamento.

Operazione	Connessione utilizzata
Query dell’applicazione	pooled (i prepared statement emulati vengono abilitati automaticamente)
Migration / `db:wipe` / `db:show` / `db:table`	direct (automatico)
`php artisan db`	direct (predefinito), passa a pooled con `--pooled`

Per usare esplicitamente la connessione direct nel codice applicativo, aggiungi il suffisso ::direct al nome della connessione.

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

Connessioni multiple al database

Puoi definire più connessioni in config/database.php e cambiarle con DB::connection().

use Illuminate\Support\Facades\DB;

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

Esecuzione di query SQL

La facade DB fornisce metodi dedicati per ciascun tipo di query.

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');

Non concatenare input degli utenti direttamente nelle stringhe SQL. Usa sempre parametri di binding per prevenire SQL injection.

Ascolto delle query

Se vuoi tracciare l’SQL eseguito, registra DB::listen() in boot() di un Service Provider.

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,
        ]);
    });
}

Transazioni

Per trattare più aggiornamenti come un’unica unità, usa DB::transaction(). Se si verifica un’eccezione, Laravel effettua automaticamente il rollback.

use Illuminate\Support\Facades\DB;

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

Se ti servono retry per deadlock, puoi specificare attempts.

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

Se vuoi controllare manualmente, usa 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;
}

Prossimi passi

Query Builder

Impara a costruire query in modo sicuro usando la configurazione della connessione.

Migrations

Impara a versionare lo schema del database a cui ti sei connesso.

Seeding

Impara a inserire dati per sviluppo e test in modo riproducibile.

Architettura

Database

Eloquent

Sicurezza

Eventi

Mail e notifiche

Pagamenti

Elaborazione asincrona

Comunicazione in tempo reale

Scheduling

Cache e ottimizzazione

Internazionalizzazione

File e storage

Debug e monitoraggio

Console e CLI

Performance

Frontend

Sviluppo con AI

Ambiente di sviluppo

Introduzione

Configurazione

Separazione delle connessioni di lettura e scrittura

Prevenire letture obsolete anche nelle richieste successive

Leggere temporaneamente dalla connessione di scrittura

Connessione PostgreSQL con pool

Connessioni multiple al database

Esecuzione di query SQL

Ascolto delle query

Transazioni

Prossimi passi

Query Builder

Migrations

Seeding

​Introduzione

​Configurazione

​Separazione delle connessioni di lettura e scrittura

​Prevenire letture obsolete anche nelle richieste successive

​Leggere temporaneamente dalla connessione di scrittura

​Connessione PostgreSQL con pool

​Connessioni multiple al database

​Esecuzione di query SQL

​Ascolto delle query

​Transazioni

​Prossimi passi

Query Builder

Migrations

Seeding

Introduzione

Configurazione

Separazione delle connessioni di lettura e scrittura

Prevenire letture obsolete anche nelle richieste successive

Leggere temporaneamente dalla connessione di scrittura

Connessione PostgreSQL con pool

Connessioni multiple al database

Esecuzione di query SQL

Ascolto delle query

Transazioni

Prossimi passi