# DBAL Support

## Installation

```php
composer require ecotone/dbal
```

### Module Powered By

Powered by powerful database abstraction layer [Doctrine/Dbal](https://github.com/doctrine/dbal) and [Enqueue](https://php-enqueue.github.io/) for asynchronous communication

## Configuration

To configure Connection follow instruction for given integration

* [Symfony Dbal Module](https://docs.ecotone.tech/modules/symfony/symfony-database-connection-dbal-module)
* [Laravel Dbal Module](https://docs.ecotone.tech/modules/laravel/database-connection-dbal-module)
* [Ecotone Lite](https://docs.ecotone.tech/modules/ecotone-lite/database-connection-dbal-module)

## Message Channel

To create Dbal Backed [Message Channel](https://docs.ecotone.tech/modelling/asynchronous-handling), we need to create [Service Context](https://docs.ecotone.tech/messaging/service-application-configuration).

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

Now `orders` channel will be available in our Messaging System.

### Message Channel Configuration

```php
DbalBackedMessageChannelBuilder::create("orders")
    ->withAutoDeclare(false) // do not auto declare queue
    ->withDefaultTimeToLive(1000) // limit TTL of messages
```

## Transactions

By default `Ecotone`enables transactions for all [Asynchronous Endpoints](https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-asynchronous-processing) and Command Bus. You may use of [`Service Context`](https://docs.ecotone.tech/messaging/service-application-configuration) to turn off this configuration. You may also add more connections to be handled.

```php
class DbalConfiguration
{
    #[ServiceContext]
    public function registerTransactions() : array
    {
        return [
            DbalConfiguration::createWithDefaults()
                ->withTransactionOnCommandBus(true) // Turn for running command bus
                ->withTransactionOnAsynchronousEndpoints(true) // for all asynchronous endpoints
                ->withoutTransactionOnAsynchronousEndpoints(["notifications"]) // turn off for list of asynchronous endpoint 
                ->withDefaultConnectionReferenceNames([
                    "Enqueue\Dbal\DbalConnectionFactory",
                    "AnotherDbalConnectionFactory"
                ])
        ];
    }

}
```

If we disable global transactions, it make sense to enable transactions on specific endpoint.\
To do it all we need to do is to mark it with `Ecotone\Dbal\DbalTransaction\DbalTransaction` attribute.

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

## Document Store

DBAL provides support for [Document Store](#undefined), which is enabled by default.\
Every document is stored inside the "`ecotone_document_store`" table.

### Standard Aggregate Repository

You may enable support for [storing standard aggregates](#standard-aggregate-repository).

```php
#[ServiceContext]
public function getDbalConfiguration(): DbalConfiguration
{
    return DbalConfiguration::createWithDefaults()
            ->withDocumentStore(enableDocumentStoreAggregateRepository: true);
}
```

### In Memory Document Store

For testing purposes you may want to enable `In Memory implementation`.

```php
#[ServiceContext]
public function configuration()
{
    return DbalConfiguration::createWithDefaults()
                ->withDocumentStore(inMemoryDocumentStore: true);
}
```

### Document Store related Aggregates

To enable specific Aggregates for Document Store Repository:

```php
#[ServiceContext]
public function getDbalConfiguration(): DbalConfiguration
{
    return DbalConfiguration::createWithDefaults()
            ->withDocumentStore(
                    enableDocumentStoreAggregateRepository: true,
                    documentStoreRelatedAggregates: [Ticket::class]
            );
}
```

### Table initialization

Table will be create for you, however this comes with extra SQL cost, to verify before adding new document, if table exists.\
After releasing you may want to disable the check, as you know, that the table already exists.

```php
    #[ServiceContext]
    public function getDbalConfiguration(): DbalConfiguration
    {
        return DbalConfiguration::createWithDefaults()
                ->withDocumentStore(initializeDatabaseTable: false);
    }
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ecotone.tech/modules/dbal-support.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.