Configurazione del database

Configurazione delle connessioni al database di Laravel, separazione read/write, connessioni multiple, esecuzione di SQL, ascolto delle query e nozioni di base sulle transazioni.

​

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.

​

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

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.