Installation

composer require ecotone/dbal

Module Powered By

Powered by powerful database abstraction layer Doctrine/Dbal and Enqueue for asynchronous communication

Configuration

In order to use Dbal Support we need to add ConnectionFactory to our Dependency Container.

Using Database Connection String

# config/services.yaml
    Enqueue\Dbal\DbalConnectionFactory:
        class: Enqueue\Dbal\DbalConnectionFactory
        arguments: ["pgsql://user:[email protected]:5432/db_name"]

# Register Service in Provider
​
use Enqueue\Dbal\DbalConnectionFactory;
​
public function register()
{
     $this->app->singleton(DbalConnectionFactory::class, function () {
         return new DbalConnectionFactory('pgsql://user:[email protected]:5432/db_name');
     });
}

Using Existing Connection

# config/services.yaml
    Enqueue\Dbal\DbalConnectionFactory:
        factory: ['Ecotone\Dbal\DbalConnection', 'create']
        arguments: ["@Doctrine\DBAL\Connection"]

# Register Service in Provider
​
use Enqueue\Dbal\DbalConnectionFactory;
use Ecotone\Dbal\DbalConnection;
​
public function register()
{
     $this->app->singleton(DbalConnectionFactory::class, function ($app) {
         return new DbalConnection::create(app("Doctrine\DBAL\Connection"));
     });
}

Using Manager Registry

If we want to make use of existing connection using Manager Registry, we can do it this way

# config/services.yaml
    Enqueue\Dbal\DbalConnectionFactory:
        class: Enqueue\Dbal\ManagerRegistryConnectionFactory
        arguments:
            - "@doctrine"
            - 
                connection_name: "default"

Message Channel

To create Dbal Backed Message Channel, we need to create Service Context.

class MessagingConfiguration
{
    #[ServiceContext] 
    public function orderChannel()
    {
        return DbalBackedMessageChannelBuilder::create("orders");
    }
}

Now orders channel will be available in our Messaging System.

Transactions

Ecotone Dbal comes with support for transactions. To enable transactions on specific endpoint, mark it with Ecotone\Dbal\DbalTransaction\DbalTransaction annotation.

    #[CommandHandler]
    #[DbalTransaction] 
    public function sellProduct(SellProduct $command) : void
    {
        // do something with $command
    }

By default Ecotoneenables transactions for all Asynchronous Endpoints and Command Bus. You may use of Service Context to turn off this configuration. You may also add more connections to be handled.

class DbalConfiguration
{
    #[ServiceContext]
    public function registerTransactions() : array
    {
        return [
            DbalConfiguration::createWithDefaults()
                ->withTransactionOnAsynchronousEndpoints(true)
                ->withTransactionOnCommandBus(true)
                ->withDefaultConnectionReferenceNames([
                    "Enqueue\Dbal\DbalConnectionFactory",
                    "AnotherDbalConnectionFactory"
                ])
        ];
    }
​
}

Dead Letter

Enable Dead Letter

Using Service Context​

#[ServiceContext]
public function dbalConfiguration()
{
    return DbalConfiguration::createWithDefaults()
        ->withDeadLetter(true);
}

Dbal comes with full support for Dead Letter. You can read more about it here.

Setting up, Dbal Dead Letter as final error channel:

#[ServiceContext]
public function errorConfiguration() {
    return ErrorHandlerConfiguration::createWithDeadLetterChannel(
        "errorChannel",
        RetryTemplateBuilder::exponentialBackoff(1000, 10)
            ->maxRetryAttempts(3),
        "dbal_dead_letter"
    );
}

In above scenario, message after failing 3 times, will be stored in database for future investigation.

Dead Letter Console Commands

Help

bin/console ecotone:deadletter:help

artisan ecotone:deadletter:help

Listing Error Messages

bin/console ecotone:deadletter:list

artisan ecotone:deadletter:list

$list = $messagingSystem->runConsoleCommand("ecotone:deadletter:list", []);

Show Details About Error Message

bin/console ecotone:deadletter:show {messageId}

artisan ecotone:deadletter:show {messageId}

$list = $messagingSystem->runConsoleCommand("ecotone:deadletter:show", ["messageId" => $messageId]);

Replay Error Message

bin/console ecotone:deadletter:replay {messageId}

artisan ecotone:deadletter:replay {messageId}

$list = $messagingSystem->runConsoleCommand("ecotone:deadletter:replay", ["messageId" => $messageId]);

Replay All Messages

bin/console ecotone:deadletter:replayAll

artisan ecotone:deadletter:replayAll

$list = $messagingSystem->runConsoleCommand("ecotone:deadletter:replayAll", []);

Delete Message

bin/console ecotone:deadletter:delete {messageId}

artisan ecotone:deadletter:delete {messageId}

$list = $messagingSystem->runConsoleCommand("ecotone:deadletter:delete", ["messageId" => $messageId]);

​