Configuración de la base de datos

Introducción

Laravel soporta oficialmente las siguientes bases de datos:

MySQL / MariaDB
PostgreSQL
SQLite
SQL Server

Puedes usar la misma configuración de conexión con SQL en crudo, Query Builder o Eloquent ORM.

Esta página cubre las bases de la conexión. Para consultas prácticas, consulta Query Builder; para gestión del esquema, Migrations; y para carga inicial de datos, Seeding.

Configuración

La configuración se concentra en config/database.php. Con default eliges el nombre de la conexión por defecto, y en connections defines los detalles de cada conexión.

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

Como mínimo, configura lo siguiente en .env:

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

Para usar SQLite, configura DB_CONNECTION=sqlite y la ruta en DB_DATABASE.

Separación de conexiones de lectura y escritura

Si quieres separar las lecturas (SELECT) y las escrituras (INSERT / UPDATE / DELETE) en hosts distintos, configura read y write dentro de la misma conexión.

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

Al poner sticky a true, dentro de la misma solicitud las lecturas posteriores a una escritura se fijan en la conexión de escritura.

En configuraciones con retraso de replicación, activar sticky reduce el riesgo de leer datos antiguos justo después de una escritura.

Evitar lecturas obsoletas también en las siguientes solicitudes

sticky solo tiene efecto dentro de la misma solicitud. Si quieres leer los datos recién escritos también en las solicitudes posteriores de la misma sesión, añade el middleware PreventStaleDatabaseReads al grupo de middleware web.

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

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

El middleware registra en la sesión las escrituras en la conexión de base de datos predeterminada. Por defecto, las solicitudes realizadas en los 2 segundos posteriores a una escritura usan la conexión de escritura para las lecturas de esa conexión. Para cambiar la duración, indica for.

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

Como este middleware depende de la sesión, debe ejecutarse después del middleware StartSession. No afecta a las lecturas de otras sesiones ni de otras conexiones de base de datos.

Leer temporalmente desde la conexión de escritura

Para fijar las lecturas dentro de un callback en la conexión de escritura, usa el método usingWritePdo de la conexión.

use Illuminate\Support\Facades\DB;

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

También se aplica a las consultas de Eloquent y de relaciones que usan la misma conexión dentro del callback. Al terminar el callback, la configuración de lectura de la conexión se restablece, se haya producido o no una excepción.

Conexión pooled a PostgreSQL

Si utilizas un servicio gestionado de PostgreSQL con pooling en modo transacción como PgBouncer, configura las opciones pooled y 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'),
    ]),
],

Al activar pooled, Laravel enruta automáticamente las operaciones.

Operación	Conexión utilizada
Consultas de la aplicación	pooled (con emulated prepares activadas automáticamente)
Migraciones / `db:wipe` / `db:show` / `db:table`	direct (automático)
`php artisan db`	direct (por defecto); con `--pooled` cambia a pooled

Si dentro del código de la aplicación quieres usar explícitamente la conexión directa, añade el sufijo ::direct al nombre de la conexión.

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

Múltiples conexiones a base de datos

Puedes definir varias conexiones en config/database.php y cambiar entre ellas con DB::connection().

use Illuminate\Support\Facades\DB;

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

Ejecución de consultas SQL

La facade DB tiene métodos específicos por tipo de consulta.

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

No concatenes directamente entradas del usuario en la cadena SQL. Usa siempre argumentos con binding para evitar inyecciones SQL.

Escucha de consultas

Si quieres rastrear las consultas ejecutadas, registra DB::listen() en el boot() de 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,
        ]);
    });
}

Transacciones

Para tratar varias actualizaciones como una unidad, usa DB::transaction(). Si se lanza una excepción, Laravel hace rollback automáticamente.

use Illuminate\Support\Facades\DB;

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

Si necesitas reintentos por deadlock, pasa attempts.

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

Para un control manual, usa beginTransaction, rollBack y 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;
}

Próximos pasos

Query Builder

Aprende a construir consultas de forma segura utilizando la configuración de conexión.

Migrations

Aprende a versionar el esquema de la base de datos conectada.

Seeding

Aprende a poblar de forma reproducible datos para desarrollo y pruebas.

Arquitectura

Base de datos

Eloquent

Seguridad

Eventos

Correo y notificaciones

Pagos

Procesamiento asíncrono

Comunicación en tiempo real

Programación de tareas

Caché y optimización

Internacionalización

Archivos y almacenamiento

Depuración y monitoreo

Consola y CLI

Rendimiento

Frontend

Desarrollo con IA

Entorno de desarrollo

Introducción

Configuración

Separación de conexiones de lectura y escritura

Evitar lecturas obsoletas también en las siguientes solicitudes

Leer temporalmente desde la conexión de escritura

Conexión pooled a PostgreSQL

Múltiples conexiones a base de datos

Ejecución de consultas SQL

Escucha de consultas

Transacciones

Próximos pasos

Query Builder

Migrations

Seeding

​Introducción

​Configuración

​Separación de conexiones de lectura y escritura

​Evitar lecturas obsoletas también en las siguientes solicitudes

​Leer temporalmente desde la conexión de escritura

​Conexión pooled a PostgreSQL

​Múltiples conexiones a base de datos

​Ejecución de consultas SQL

​Escucha de consultas

​Transacciones

​Próximos pasos

Query Builder

Migrations

Seeding

Introducción

Configuración

Separación de conexiones de lectura y escritura

Evitar lecturas obsoletas también en las siguientes solicitudes

Leer temporalmente desde la conexión de escritura

Conexión pooled a PostgreSQL

Múltiples conexiones a base de datos

Ejecución de consultas SQL

Escucha de consultas

Transacciones

Próximos pasos