feat: add sqla broker

.github/workflows/pr_tests.yaml

@@ -456,6 +456,61 @@ jobs:
           if-no-files-found: error
           include-hidden-files: true
 
+  test-sqla-real:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    needs:
+      - test-basic
+    services:
+      postgres:
+        image: postgres:latest # zizmor: ignore[unpinned-images]
+        env:
+          POSTGRES_DB: broker
+          POSTGRES_USER: broker
+          POSTGRES_PASSWORD: brokerpass # pragma: allowlist secret
+        ports:
+          - 5432:5432
+      mysql:
+        image: mysql:latest # zizmor: ignore[unpinned-images]
+        env:
+          MYSQL_DATABASE: broker
+          MYSQL_USER: broker
+          MYSQL_PASSWORD: brokerpass # pragma: allowlist secret
+          MYSQL_ROOT_PASSWORD: brokerpass # pragma: allowlist secret
+        ports:
+          - 3306:3306
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Grant MySQL privileges
+        run: |
+          until mysqladmin ping -h 127.0.0.1 --silent; do sleep 1; done
+          mysql -h 127.0.0.1 -u root -pbrokerpass < tests/brokers/sqla/infra/init_mysql.sql
+      - uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          version: "latest"
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.13"
+      - name: Install Dependencies
+        run: |
+          uv pip install --system --group optionals --group testing .
+      - name: Test
+        run: >
+          pytest --cov --cov-report=
+          -vv -m "(slow and sqla and connected) or (sqla and connected)"
+      - name: Rename coverage file
+        run: mkdir coverage && mv .coverage coverage/.coverage.sqla-py
+      - name: Store coverage files
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: .coverage.sqla-py
+          path: coverage
+          if-no-files-found: error
+          include-hidden-files: true
+
   coverage-combine:
     if: github.event.pull_request.draft == false
     needs:

docker-compose.yaml

@@ -41,6 +41,31 @@ services:
     security_opt:
       - no-new-privileges:true
 
+  postgres:
+    image: postgres:latest
+    environment:
+      POSTGRES_DB: broker
+      POSTGRES_USER: broker
+      POSTGRES_PASSWORD: brokerpass # pragma: allowlist secret
+    ports:
+      - "5432:5432"
+    security_opt:
+      - no-new-privileges:true
+
+  mysql:
+    image: mysql:latest
+    environment:
+      MYSQL_DATABASE: broker
+      MYSQL_USER: broker
+      MYSQL_PASSWORD: brokerpass # pragma: allowlist secret
+      MYSQL_ROOT_PASSWORD: brokerpass # pragma: allowlist secret
+    ports:
+      - "3306:3306"
+    volumes:
+      - ./tests/brokers/sqla/infra/init_mysql.sql:/docker-entrypoint-initdb.d/99-grant-all.sql:ro
+    security_opt:
+      - no-new-privileges:true
+
   faststream:
     build: .
     volumes:

docs/docs/en/getting-started/acknowledgement.md

@@ -14,6 +14,7 @@ Due to the possibility of unexpected errors during message processing, FastStrea
 - [**RabbitMQ**](../rabbit/index.md){.internal-link}
 - [**NATS JetStream**](../nats/jetstream/index.md){.internal-link}
 - [**Redis Streams**](../redis/streams/index.md){.internal-link}
+- [**SQLA**](../sqla/index.md){.internal-link}
 
 ### Usage
 
@@ -36,17 +37,25 @@ async def handler(msg: str, logger: Logger) -> None:
 
 ### Available Options
 
-Each `AckPolicy` variant includes behavior examples for both successful processing and error scenarios. Note that broker-specific behaviors are also included.
+| Policy | Description | On Success | On Error |
+| --- | --- | --- | --- |
+| `ACK_FIRST` | ACK upon receipt, prior to processing | ACK | ACK |
+| `ACK` | ACK after processing, regardless of exceptions | ACK | ACK |
+| `REJECT_ON_ERROR` | ACK on successful processing, REJECT on exception (no redelivery) | ACK | REJECT |
+| `NACK_ON_ERROR` | ACK on successful processing, NACK on exception (with redelivery) | ACK | NACK |
+| `MANUAL` | No automatic acknowledgement. User must manually handle the completion via message methods<ul><li> `#!python msg.ack()`</li><li>`#!python msg.nack()`<li>`#!python msg.reject()`</li></ul> | | |
 
-| Policy                      | Description                                                                                                                             | On Success                                                                   | On Error                                              | Broker Notes                                                             |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------ |
-| `ACK_FIRST`       | Acknowledge immediately upon receipt, before processing begins.                                                                         | Message is acknowledged early;<br/>may be lost if processing fails.              | Acknowledged despite error;<br/>message not re-delivered. | Kafka commits offset;<br/>NATS, Redis, and RabbitMQ acknowledge immediately. |
-| `ACK`             | Acknowledge only after processing completes, regardless of success.                                                                     | Ack after success.                                          | Ack sent anyway;<br/>message not redelivered.             | Kafka: offset commit; others: explicit ack.                              |
-| `REJECT_ON_ERROR` | Reject message if an unhandled exception occurs, permanently discarding it;<br/>otherwise, ack.                                             | Ack after success. | Message discarded; no retry.                          | RabbitMQ/NATS drops message. Kafka commits offset.                       |
-| `NACK_ON_ERROR`   | Nack on error to allow message redelivery, ack after success otherwise.                                                                 | Ack after success.                                                           | Redeliver; attempt to resend message.                 | Redis Streams and RabbitMQ redelivers; Kafka commits as fallback.        |
-| `MANUAL`      | No automatic acknowledgement. User must manually handle the completion via message methods<ul><li> `#!python msg.ack()`</li><li>`#!python msg.nack()`<li>`#!python msg.reject()`</li></ul> | | | |
+### Broker Behaviors
 
----
+Here is how **FastStream's** ACK / NACK / REJECT commands map to brokers' behaviors:
+
+| Broker | `ACK` | `NACK` | `REJECT` |
+| ------ | ----- | ------ | -------- |
+| [RabbitMQ](https://www.rabbitmq.com/docs/confirms#acknowledgement-modes){.external-link target="_blank"} | Protocol ack            | Protocol nack | Protocol reject |
+| [NATS JetStream](https://docs.nats.io/using-nats/developer/develop_jetstream#acknowledging-messages){.external-link target="_blank"} | Protocol ack            | Protocol nak  | Protocol term   |
+| [Redis Streams](https://redis.io/docs/latest/commands/xack/){.external-link target="_blank"} | Xack call               | Do nothing    | Do nothing      |
+| Kafka | Commits offset          | Seek offset and read message again    | Commits offset (same as `ACK`)      |
+| [SQLA](../sqla/index.md){.internal-link} | Mark msg as COMPLETED | Mark msg as RETRYABLE if retry strategy allows and FAILED otherwise | Mark msg as FAILED |
 
 ### When to Use
 
@@ -56,8 +65,6 @@ Each `AckPolicy` variant includes behavior examples for both successful processi
 - Use `NACK_ON_ERROR` to retry messages in case of failure.
 - Use `MANUAL` to fully manually control message acknowledgment (for example, calling `#!python message.ack()` yourself).
 
----
-
 ### Extended Examples
 
 #### Automatic Retry on Failure
@@ -95,14 +102,3 @@ async def handle_event(msg: str) -> None:
 ```
 
 You can also manage manual acknowledgement using middleware. For more information, [error handling middleware documentation](./middlewares/exception.md){.internal-link}.
-
-### Broker Behavior Summary
-
-However, not all brokers support our semantics. Here is a brief overview of **FastStream's** ACK / NACK / REJECT command mapping to brokers' acknowledgment policies:
-
-| Broker | `ACK` | `NACK` | `REJECT` |
-| ------ | ----- | ------ | -------- |
-| [RabbitMQ](https://www.rabbitmq.com/docs/confirms#acknowledgement-modes){.external-link target="_blank"} | Protocol ack            | Protocol nack | Protocol reject |
-| [NATS JetStream](https://docs.nats.io/using-nats/developer/develop_jetstream#acknowledging-messages){.external-link target="_blank"} | Protocol ack            | Protocol nak  | Protocol term   |
-| [Redis Streams](https://redis.io/docs/latest/commands/xack/){.external-link target="_blank"} | Xack call               | Do nothing    | Do nothing      |
-| Kafka | Commits offset          | Seek offset and read message again    | Commits offset (same as `ACK`)      |