> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  Questa pagina copre le premesse sulle connessioni al database. Per le query pratiche consulta [Query Builder](/it/query-builder), per la gestione dello schema le [Migration](/it/migrations), per l'inserimento dei dati iniziali il [Seeding](/it/seeding).
</Info>

## Configurazione

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

```mermaid theme={null}
flowchart TD
    A[".env"] --> B["config/database.php"]
    B --> C["default connection"]
    B --> D["connections.mysql"]
    B --> E["connections.pgsql"]
    B --> F["connections.sqlite"]
    C --> G["DB facade / Query Builder / Eloquent"]
```

```php theme={null}
// 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.

```ini theme={null}
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.

```php theme={null}
'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.

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

## 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`.

```php theme={null}
'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.

```php theme={null}
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()`.

```php theme={null}
use Illuminate\Support\Facades\DB;

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

```mermaid theme={null}
flowchart LR
    A["DB::connection('mysql')"] --> B["Primary DB"]
    C["DB::connection('pgsql')"] --> D["Analytics DB"]
    E["DB::connection('sqlite')"] --> F["Local file DB"]
```

## Esecuzione di query SQL

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

```php theme={null}
use Illuminate\Support\Facades\DB;

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

DB::insert('insert into users (name, email) values (?, ?)', ['Taylor', 'taylor@example.com']);

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

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

## Ascolto delle query

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

```php theme={null}
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.

```php theme={null}
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`.

```php theme={null}
DB::transaction(function () {
    // ...
}, attempts: 5);
```

Se vuoi controllare manualmente, usa `beginTransaction` / `rollBack` / `commit`.

```php theme={null}
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

<Card title="Query Builder" icon="table" href="/it/query-builder">
  Impara a costruire query in modo sicuro usando la configurazione della connessione.
</Card>

<Card title="Migrations" icon="hammer" href="/it/migrations">
  Impara a versionare lo schema del database a cui ti sei connesso.
</Card>

<Card title="Seeding" icon="seedling" href="/it/seeding">
  Impara a inserire dati per sviluppo e test in modo riproducibile.
</Card>


## Related topics

- [Installazione](/it/installation.md)
- [Socialite - Laravel Bluesky](/it/packages/laravel-bluesky/socialite.md)
- [Sessioni](/it/session.md)
- [Migration del database](/it/migrations.md)
- [Test del database](/it/database-testing.md)