Extensión de conexiones de base de datos en paquetes

​

Elegir el punto de extensión

​

La extensión por nombre de conexión tiene prioridad sobre el nombre de driver

• DB::extend('reporting', ...) se aplica a database.connections.reporting.
• DB::extend('mysql', ...) se aplica a las conexiones cuyo driver es mysql y que no tienen una extensión por nombre de conexión.
• Ambos usan el mismo registro de extensiones. Ten en cuenta también los conflictos entre nombres de conexión y nombres de driver, y usa nombres propios del paquete.
• extend() no crea el array de configuración. Si solo registras la extensión y no existe la configuración de la conexión con ese nombre, se lanzará una excepción.

​

Seleccionar explícitamente un nombre de driver propio

<?php

namespace Acme\DatabaseBridge;

use Illuminate\Database\Connection;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\ServiceProvider;

final class DatabaseBridgeServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $app = $this->app;

        DB::extend('acme-sqlite', function (array $config, string $name) use ($app): Connection {
            $config['driver'] = 'sqlite';

            return $app->make('db.factory')->make($config, $name);
        });
    }
}

'acme_reports' => [
    'driver' => 'acme-sqlite',
    'database' => database_path('reports.sqlite'),
    'prefix' => '',
    'foreign_key_constraints' => true,
],

use Illuminate\Support\Facades\DB;

$connection = DB::connection('acme_reports');
$rows = $connection->select('select 1 as value');

​

Reemplazar por una subclase de Connection es otro alcance

• En el callback, devuelve una subclase de Connection para la BD objetivo. Con la Connection base por sí sola no se conservan el Grammar, el Processor y demás elementos propios de la BD.
• El Factory separa createConnector() de createConnection(). Registrar solo resolverFor() no proporciona un conector PDO para un driver desconocido.
• Si el resolver propio de DB::extend() no usa el Factory estándar, tampoco pasa por la comprobación de resolverFor() dentro del Factory.
• Volver a registrar el mismo driver lo sobrescribe. Comprueba los conflictos con otros paquetes y que no se arrastre entre pruebas dentro del mismo proceso PHP.

​

Distinguir reconnect y purge

​

Probar el registro y la creación del paquete

<?php

namespace Acme\DatabaseBridge\Tests;

use Acme\DatabaseBridge\DatabaseBridgeServiceProvider;
use Illuminate\Database\SQLiteConnection;
use Orchestra\Testbench\TestCase;

final class DatabaseBridgeTest extends TestCase
{
    protected function getPackageProviders($app): array
    {
        return [DatabaseBridgeServiceProvider::class];
    }

    protected function defineEnvironment($app): void
    {
        $app['config']->set('database.default', 'testing');
        $app['config']->set('database.connections.acme_reports', [
            'driver' => 'acme-sqlite',
            'database' => ':memory:',
            'prefix' => '',
        ]);
    }

    public function test_registration_does_not_create_connections(): void
    {
        $manager = $this->app->make('db');

        $this->assertSame('testing', $manager->getDefaultConnection());
        $this->assertArrayNotHasKey('acme_reports', $manager->getConnections());
    }

    public function test_connection_is_reused_and_purge_creates_a_new_one(): void
    {
        $manager = $this->app->make('db');
        $first = $manager->connection('acme_reports');

        $this->assertInstanceOf(SQLiteConnection::class, $first);
        $this->assertSame('acme_reports', $first->getName());
        $this->assertSame('sqlite', $first->getDriverName());
        $this->assertSame(1, (int) $first->selectOne('select 1 as value')->value);
        $this->assertSame($first, $manager->connection('acme_reports'));
        $this->assertSame($first, $manager->reconnect('acme_reports'));

        $manager->purge('acme_reports');

        $second = $manager->connection('acme_reports');

        $this->assertNotSame($first, $second);
        $this->assertSame(1, (int) $second->selectOne('select 1 as value')->value);
    }
}

• Que el resolver por nombre de conexión tenga prioridad sobre el resolver por nombre de driver.
• Que volver a registrar el mismo nombre y forgetExtension() no reemplacen las Connection ya creadas.
• Las excepciones cuando falta configuración obligatoria y el comportamiento cuando falla la conexión.
• Las funciones que te comprometes a ofrecer, como migraciones, transacciones o separación read/write en las BD compatibles.
• Que el registro y el estado de las conexiones no se mezclen en workers de larga duración ni al combinarse con varios paquetes.

​

Puntos de comprobación para el mantenimiento

• ¿Se activa mediante un nombre propio (opt-in) sin sobrescribir en silencio la conexión predeterminada ni los drivers integrados?
• ¿Evitas meter Closures u objetos de conexión en la caché de configuración y colocas la lógica de creación en el provider?
• ¿Gestionas los destinos de conexión y las credenciales como configuración de aplicación de confianza?
• ¿Has vuelto a comprobar los argumentos de extend(), el orden de creación del Factory y lo que transfiere reconnect() en las versiones de Laravel soportadas?
• ¿Indicas a los usuarios el procedimiento de regeneración tras cambiar la configuración y el reinicio de los workers?

​

Páginas relacionadas

• Desarrollo de paquetes
• Diseño del ciclo de vida de los servicios de paquetes
• Fusión y caché de la configuración de paquetes
• Publicación y actualización de migraciones de paquetes

​

Fuentes primarias consultadas

• Documentación oficial de Laravel: base de datos y múltiples conexiones
• Documentación oficial de Laravel: service providers de paquetes
• DatabaseManager: orden de creación, registro de extensiones, retención de conexiones y reconexión
• ConnectionFactory: creación diferida del PDO y resolver de Connection
• Connection: resolverFor y getResolver
• DatabaseServiceProvider: registro de db y db.factory