feature: postgresql phpunit bridge (#2299)

- wrap tests in transactions
- add phpunit postgresql bridge as optional dependency of postgresql
bundle

Author: norberttech

.codecov.yaml

@@ -172,6 +172,10 @@ component_management:
       name: adapter-postgresql
       paths:
         - src/adapter/etl-adapter-postgresql/**
+    - component_id: bridge-phpunit-postgresql
+      name: bridge-phpunit-postgresql
+      paths:
+        - src/bridge/phpunit/postgresql/**
     - component_id: bridge-phpunit-telemetry
       name: bridge-phpunit-telemetry
       paths:

.github/workflows/monorepo-split.yml

@@ -104,6 +104,8 @@ jobs:
             split_repository: 'symfony-telemetry-bundle'
           - local_path: 'src/bridge/telemetry/otlp'
             split_repository: 'telemetry-otlp-bridge'
+          - local_path: 'src/bridge/phpunit/postgresql'
+            split_repository: 'phpunit-postgresql-bridge'
           - local_path: 'src/bridge/phpunit/telemetry'
             split_repository: 'phpunit-telemetry-bridge'
 

composer.json

@@ -116,6 +116,7 @@
         "flow-php/telemetry": "self.version",
         "flow-php/telemetry-otlp-bridge": "self.version",
         "flow-php/types": "self.version",
+        "flow-php/phpunit-postgresql-bridge": "self.version",
         "flow-php/phpunit-telemetry": "self.version",
         "flow-php/phpunit-telemetry-bridge": "self.version"
     },
@@ -152,6 +153,7 @@
                 "src/bridge/symfony/postgresql-messenger/src/Flow",
                 "src/bridge/symfony/telemetry-bundle/src/Flow",
                 "src/bridge/telemetry/otlp/src/Flow",
+                "src/bridge/phpunit/postgresql/src/Flow",
                 "src/bridge/phpunit/telemetry/src/Flow",
                 "src/cli/src/Flow",
                 "src/core/etl/src/Flow",
@@ -194,6 +196,7 @@
             "src/bridge/filesystem/azure/src/Flow/Filesystem/Bridge/Azure/DSL/functions.php",
             "src/bridge/monolog/http/src/Flow/Bridge/Monolog/Http/DSL/functions.php",
             "src/bridge/monolog/telemetry/src/Flow/Bridge/Monolog/Telemetry/DSL/functions.php",
+            "src/bridge/phpunit/postgresql/src/Flow/Bridge/PHPUnit/PostgreSQL/DSL/functions.php",
             "src/bridge/openapi/specification/src/Flow/Bridge/OpenAPI/Specification/DSL/functions.php",
             "src/bridge/psr7/telemetry/src/Flow/Bridge/Psr7/Telemetry/DSL/functions.php",
             "src/bridge/psr18/telemetry/src/Flow/Bridge/Psr18/Telemetry/DSL/functions.php",
@@ -253,6 +256,7 @@
                 "src/bridge/symfony/postgresql-messenger/tests/Flow",
                 "src/bridge/symfony/telemetry-bundle/tests/Flow",
                 "src/bridge/telemetry/otlp/tests/Flow",
+                "src/bridge/phpunit/postgresql/tests/Flow",
                 "src/bridge/phpunit/telemetry/tests/Flow",
                 "src/cli/tests/Flow",
                 "src/core/etl/tests/Flow",
@@ -321,6 +325,7 @@
             "@test:bridge:monolog-http",
             "@test:bridge:monolog-telemetry",
             "@test:bridge:openapi-specification",
+            "@test:bridge:phpunit-postgresql",
             "@test:bridge:phpunit-telemetry",
             "@test:bridge:psr7-telemetry",
             "@test:bridge:psr18-telemetry",
@@ -496,6 +501,10 @@
             "tools/phpunit/vendor/bin/phpunit --testsuite=adapter-postgresql-unit --log-junit ./var/phpunit/logs/adapter-postgresql-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/adapter-postgresql-unit.coverage.xml",
             "tools/phpunit/vendor/bin/phpunit --testsuite=adapter-postgresql-integration --log-junit ./var/phpunit/logs/adapter-postgresql-integration.junit.xml --coverage-clover=./var/phpunit/coverage/clover/adapter-postgresql-integration.coverage.xml"
         ],
+        "test:bridge:phpunit-postgresql": [
+            "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-phpunit-postgresql-unit --log-junit ./var/phpunit/logs/bridge-phpunit-postgresql-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-phpunit-postgresql-unit.coverage.xml",
+            "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-phpunit-postgresql-integration --log-junit ./var/phpunit/logs/bridge-phpunit-postgresql-integration.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-phpunit-postgresql-integration.coverage.xml"
+        ],
         "test:bridge:phpunit-telemetry": [
             "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-phpunit-telemetry-unit --log-junit ./var/phpunit/logs/bridge-phpunit-telemetry-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-phpunit-telemetry-unit.coverage.xml"
         ],

documentation/components/bridges/phpunit-postgresql-bridge.md

@@ -0,0 +1,92 @@
+# PHPUnit PostgreSQL Bridge
+
+PHPUnit extension for flow-php/postgresql that can wrap tests in transactions.
+
+- [Back](/documentation/introduction.md)
+- [Packagist](https://packagist.org/packages/flow-php/phpunit-postgresql-bridge)
+- [➡️ Installation](/documentation/installation/packages/phpunit-postgresql-bridge.md)
+- [GitHub](https://github.com/flow-php/phpunit-postgresql-bridge)
+- [API Reference](/documentation/api/bridge/phpunit/postgresql)
+
+[TOC]
+
+## Installation
+
+For detailed installation instructions, see the [installation page](/documentation/installation/packages/phpunit-postgresql-bridge.md).
+
+## Usage
+
+### PHPUnit Extension Configuration
+
+Add the extension to your `phpunit.xml` or `phpunit.xml.dist`:
+
+```xml
+<extensions>
+    <bootstrap class="Flow\Bridge\PHPUnit\PostgreSQL\PostgreSQLExtension"/>
+</extensions>
+```
+
+### Connecting to the Database
+
+Use the `static_pgsql_client()` DSL function instead of `pgsql_client()` in your tests:
+
+```php
+use function Flow\Bridge\PHPUnit\PostgreSQL\DSL\static_pgsql_client;
+use function Flow\PostgreSql\DSL\pgsql_connection_dsn;
+
+$client = static_pgsql_client(pgsql_connection_dsn($dsn));
+```
+
+When the PHPUnit extension is active, this returns a cached client wrapped in a transaction. When inactive, it delegates directly to `PgSqlClient::connect`.
+
+For Symfony bundle integration, see the [PostgreSQL Bundle documentation](/documentation/components/bridges/symfony-postgresql-bundle.md).
+
+### How It Works
+
+1. When PHPUnit starts, the extension enables `StaticClient` caching
+2. Before each test, the extension rolls back any previous transaction and begins a new one
+3. All database operations during the test run inside this transaction
+4. When the test ends, the next test's preparation rolls back all changes
+5. After all tests finish, all connections are closed
+
+This means database changes made during a test are automatically undone, keeping your test database clean.
+
+### Nested Transactions
+
+The flow-php/postgresql library supports nested transactions via SAVEPOINTs. If your test code calls `beginTransaction()`, it creates a savepoint (level 2+). When the extension rolls back (level 1), all nested changes are undone.
+
+### Skipping Transaction Rollback
+
+Use the `#[SkipTransactionRollback]` attribute to opt out of transaction wrapping for specific tests:
+
+```php
+use Flow\Bridge\PHPUnit\PostgreSQL\SkipTransactionRollback;
+
+// Skip for an entire class
+#[SkipTransactionRollback]
+final class MigrationTest extends TestCase
+{
+    // Tests in this class will NOT be wrapped in a transaction
+}
+
+// Skip for a specific method
+final class SomeTest extends TestCase
+{
+    #[SkipTransactionRollback]
+    public function test_something_that_needs_real_commits(): void
+    {
+        // This test will NOT be wrapped in a transaction
+    }
+}
+
+// Skip via abstract parent class (applies to all subclasses)
+#[SkipTransactionRollback]
+abstract class AbstractMigrationTest extends TestCase
+{
+}
+
+final class ConcreteMigrationTest extends AbstractMigrationTest
+{
+    // Inherits skip behavior from parent
+}
+```

documentation/components/bridges/symfony-postgresql-bundle.md

@@ -358,6 +358,54 @@ The `MessengerCatalogProvider` is registered automatically when `messenger.enabl
 
 For full documentation, see the [Symfony PostgreSQL Messenger Bridge](/documentation/components/bridges/symfony-postgresql-messenger-bridge.md).
 
+## Test Transaction Rollback
+
+The bundle integrates with [flow-php/phpunit-postgresql-bridge](/documentation/components/bridges/phpunit-postgresql-bridge.md) to automatically wrap each PHPUnit test in a database transaction and roll it back after the test finishes — keeping your test database clean without manual teardown.
+
+### Setup
+
+1. Install the PHPUnit bridge:
+
+```bash
+composer require --dev flow-php/phpunit-postgresql-bridge:~--FLOW_PHP_VERSION--
+```
+
+2. Register the PHPUnit extension in `phpunit.xml.dist`:
+
+```xml
+<extensions>
+    <bootstrap class="Flow\Bridge\PHPUnit\PostgreSQL\PostgreSQLExtension"/>
+</extensions>
+```
+
+3. Enable transaction rollback per connection in a test-environment config:
+
+```yaml
+# config/packages/test/flow_postgresql.yaml
+flow_postgresql:
+    connections:
+        default:
+            test_transaction_rollback: true
+        readonly:
+            test_transaction_rollback: false  # default, no wrapping
+```
+
+When `test_transaction_rollback` is `true`, the bundle replaces `PgSqlClient::connect` with `StaticClient::connect` for that connection. This ensures the exact same `Client` instance is reused across kernel reboots within the same test, so the transaction started by the PHPUnit extension covers all database operations performed by your services.
+
+### How It Works
+
+1. PHPUnit starts → extension enables `StaticClient` caching
+2. Before each test → extension rolls back the previous transaction and begins a new one
+3. Symfony kernel boots → bundle creates the client via `StaticClient::connect()` → returns the cached instance with an active transaction
+4. Test runs → all queries go through the same cached client, inside the transaction
+5. Next test starts → extension rolls back all changes from the previous test
+
+PostgreSQL supports transactional DDL, so even `CREATE TABLE` and `ALTER TABLE` statements are rolled back.
+
+### Skipping Rollback
+
+Use the `#[SkipTransactionRollback]` attribute to opt out for specific tests, classes, or abstract parent classes. See the [PHPUnit PostgreSQL Bridge documentation](/documentation/components/bridges/phpunit-postgresql-bridge.md) for details.
+
 ## Complete Example
 
 ```yaml

documentation/installation.md

@@ -62,6 +62,7 @@ Instead of installing whole repository with all dependencies, it's recommended t
 - [Monolog HTTP Bridge](/documentation/installation/packages/monolog-http-bridge.md)
 - [Monolog Telemetry Bridge](/documentation/installation/packages/monolog-telemetry-bridge.md)
 - [OpenAPI Specification Bridge](/documentation/installation/packages/openapi-specification-bridge.md)
+- [PHPUnit PostgreSQL Bridge](/documentation/installation/packages/phpunit-postgresql-bridge.md)
 - [PHPUnit Telemetry Bridge](/documentation/installation/packages/phpunit-telemetry-bridge.md)
 - [PSR-18 Telemetry Bridge](/documentation/installation/packages/psr18-telemetry-bridge.md)
 - [PSR-7 Telemetry Bridge](/documentation/installation/packages/psr7-telemetry-bridge.md)
@@ -114,6 +115,7 @@ Instead of installing whole repository with all dependencies, it's recommended t
 | [flow-php/monolog-http-bridge](/documentation/installation/packages/monolog-http-bridge.md)                                           | [![Total Downloads](https://poser.pugx.org/flow-php/monolog-http-bridge/downloads)](https://packagist.org/packages/flow-php/monolog-http-bridge)                                           | [![Latest Stable Version](https://poser.pugx.org/flow-php/monolog-http-bridge/v/stable)](https://packagist.org/packages/flow-php/monolog-http-bridge)                                           |
 | [flow-php/monolog-telemetry-bridge](/documentation/installation/packages/monolog-telemetry-bridge.md)                                 | [![Total Downloads](https://poser.pugx.org/flow-php/monolog-telemetry-bridge/downloads)](https://packagist.org/packages/flow-php/monolog-telemetry-bridge)                                 | [![Latest Stable Version](https://poser.pugx.org/flow-php/monolog-telemetry-bridge/v/stable)](https://packagist.org/packages/flow-php/monolog-telemetry-bridge)                                 |
 | [flow-php/openapi-specification-bridge](/documentation/installation/packages/openapi-specification-bridge.md)                         | [![Total Downloads](https://poser.pugx.org/flow-php/openapi-specification-bridge/downloads)](https://packagist.org/packages/flow-php/openapi-specification-bridge)                         | [![Latest Stable Version](https://poser.pugx.org/flow-php/openapi-specification-bridge/v/stable)](https://packagist.org/packages/flow-php/openapi-specification-bridge)                         |
+| [flow-php/phpunit-postgresql-bridge](/documentation/installation/packages/phpunit-postgresql-bridge.md)                               | [![Total Downloads](https://poser.pugx.org/flow-php/phpunit-postgresql-bridge/downloads)](https://packagist.org/packages/flow-php/phpunit-postgresql-bridge)                               | [![Latest Stable Version](https://poser.pugx.org/flow-php/phpunit-postgresql-bridge/v/stable)](https://packagist.org/packages/flow-php/phpunit-postgresql-bridge)                               |
 | [flow-php/phpunit-telemetry-bridge](/documentation/installation/packages/phpunit-telemetry-bridge.md)                                 | [![Total Downloads](https://poser.pugx.org/flow-php/phpunit-telemetry-bridge/downloads)](https://packagist.org/packages/flow-php/phpunit-telemetry-bridge)                                 | [![Latest Stable Version](https://poser.pugx.org/flow-php/phpunit-telemetry-bridge/v/stable)](https://packagist.org/packages/flow-php/phpunit-telemetry-bridge)                                 |
 | [flow-php/psr18-telemetry-bridge](/documentation/installation/packages/psr18-telemetry-bridge.md)                                     | [![Total Downloads](https://poser.pugx.org/flow-php/psr18-telemetry-bridge/downloads)](https://packagist.org/packages/flow-php/psr18-telemetry-bridge)                                     | [![Latest Stable Version](https://poser.pugx.org/flow-php/psr18-telemetry-bridge/v/stable)](https://packagist.org/packages/flow-php/psr18-telemetry-bridge)                                     |
 | [flow-php/psr7-telemetry-bridge](/documentation/installation/packages/psr7-telemetry-bridge.md)                                       | [![Total Downloads](https://poser.pugx.org/flow-php/psr7-telemetry-bridge/downloads)](https://packagist.org/packages/flow-php/psr7-telemetry-bridge)                                       | [![Latest Stable Version](https://poser.pugx.org/flow-php/psr7-telemetry-bridge/v/stable)](https://packagist.org/packages/flow-php/psr7-telemetry-bridge)                                       |

documentation/installation/packages/phpunit-postgresql-bridge.md

@@ -0,0 +1,24 @@
+---
+seo_title: "Installing PHPUnit PostgreSQL Bridge"
+seo_description: >
+  How to install flow-php/phpunit-postgresql-bridge in your PHP project using Composer.
+---
+
+# PHPUnit PostgreSQL Bridge
+
+- [⬅️️ Back](/documentation/installation.md)
+- [📜 Documentation](/documentation/components/bridges/phpunit-postgresql-bridge.md)
+- [📦 Packagist](https://packagist.org/packages/flow-php/phpunit-postgresql-bridge)
+
+[TOC]
+
+## Composer
+
+```bash
+composer require flow-php/phpunit-postgresql-bridge:~--FLOW_PHP_VERSION--
+```
+
+## Core Dependencies
+
+- [flow-php/postgresql](https://packagist.org/packages/flow-php/postgresql)
+- [phpunit/phpunit](https://packagist.org/packages/phpunit/phpunit)

manifest.json

@@ -151,6 +151,11 @@
       "path": "src/lib/postgresql",
       "type": "lib"
     },
+    {
+      "name": "flow-php/phpunit-postgresql-bridge",
+      "path": "src/bridge/phpunit/postgresql",
+      "type": "bridge"
+    },
     {
       "name": "flow-php/phpunit-telemetry-bridge",
       "path": "src/bridge/phpunit/telemetry",

phpdoc/bridge.phpunit.postgresql.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor
+        configVersion="3"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://www.phpdoc.org"
+>
+    <title>Flow PHP</title>
+    <paths>
+        <output>./../web/landing/build/documentation/api/bridge/phpunit/postgresql</output>
+        <cache>./../var/phpdocumentor/cache/bridge/phpunit/postgresql</cache>
+    </paths>
+    <version number="1.x">
+        <api format="php">
+            <source dsn="./../">
+                <path>src/bridge/phpunit/postgresql/src</path>
+            </source>
+            <output>postgresql</output>
+            <default-package-name>PHPUnit PostgreSQL</default-package-name>
+            <visibility>public</visibility>
+            <include-source>false</include-source>
+        </api>
+    </version>
+    <setting name="template.color" value="orange"/>
+</phpdocumentor>

phpstan.neon

@@ -48,6 +48,8 @@ parameters:
         - src/lib/types/src
         - src/lib/postgresql/src
         - src/tools/documentation/src
+        - src/bridge/phpunit/postgresql/src
+        - src/bridge/phpunit/postgresql/tests
         - src/bridge/phpunit/telemetry/src
         - src/bridge/phpunit/telemetry/tests
         - src/core/etl/tests