Savepoint Prevent Crash Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Problem-Specific Solution: Directly addresses a known Doctrine/MariaDB issue (ORM #11230) where savepoint rollbacks crash the connection, causing silent failures or partial transactions. This aligns well with systems relying on ACID compliance in transaction-heavy workflows (e.g., e-commerce, banking, or inventory systems).
• Symfony/Doctrine-Centric: Optimized for Symfony applications using Doctrine ORM. If the stack is Laravel, integration requires DoctrineBridge or a custom adapter layer (see Integration Approach).
• Non-Invasive: Zero configuration required; leverages middleware for automatic handling. Ideal for legacy systems where modifying core transaction logic is risky.
• Complementary to Retry Logic: Works alongside the author’s doctrine-retry-bundle, suggesting use cases where idempotency + transaction safety are critical (e.g., payment processing).

Integration Feasibility

• Laravel Compatibility:
  • Doctrine in Laravel: Requires doctrine/dbal or doctrine/orm (via packages like laravel-doctrine/orm). The bundle’s core logic (savepoint rollback handling) is DBAL-agnostic, but Symfony-specific middleware (e.g., EventDispatcher) may need adaptation.
  • Middleware Replacement: Laravel’s middleware pipeline can emulate Symfony’s event-based approach using kernel middleware or Doctrine event listeners.
• Transaction Isolation: Works with BEGIN, SAVEPOINT, and ROLLBACK TO syntax. Laravel’s database layer supports these natively (via DB::transaction() or DB::connection()->beginTransaction()).
• Testing Overhead: Requires unit tests for savepoint/rollback edge cases (e.g., nested transactions, connection drops). Laravel’s DatabaseMigrations or PestPHP can simulate MariaDB-specific behaviors.

Technical Risk

• Undocumented Assumptions:
  • Relies on MariaDB/MySQL’s savepoint behavior. PostgreSQL/SQLite may behave differently (no risk if DB is fixed).
  • No benchmarks for performance impact of savepoint overhead. Could degrade throughput in high-frequency transaction systems (e.g., 10K+ TPS).
• Laravel-Specific Gaps:
  • Symfony’s EventDispatcher is replaced by Laravel’s service container + listeners. The bundle’s SavepointCrashListener would need a Laravel-compatible rewrite.
  • No Laravel-specific tests: Risk of hidden dependencies (e.g., Symfony’s HttpFoundation).
• Rollback Propagation:
  • If Laravel’s DB::rollBack() is used outside Doctrine, the bundle’s middleware may not intercept. Requires global exception handling (e.g., App\Exceptions\Handler) to delegate to the bundle’s logic.

Key Questions

1. Database Layer:
   • Is the application using raw PDO, Doctrine DBAL, or Eloquent? The bundle targets DBAL directly.
   • Are savepoints explicitly used in custom queries, or only via Doctrine?
2. Transaction Scope:
   • Are transactions short-lived (e.g., API requests) or long-running (e.g., CLI jobs)? Long-running transactions may hit MariaDB’s max_execution_time.
3. Fallback Strategy:
   • What’s the plan if the bundle fails to prevent crashes? (e.g., log + retry vs. manual intervention).
4. Testing:
   • Can MariaDB-specific behaviors (e.g., SQLSTATE[HY000]: General error) be mocked in Laravel’s test environment?
5. Alternatives:
   • Has the team evaluated Doctrine’s native solutions (e.g., Connection::beginTransaction() with custom error handling) or database-level retries (e.g., innodb_rollback_on_timeout)?

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Proof of Concept

   • Fork the bundle and replace Symfony dependencies:
     • symfony/event-dispatcher → Laravel’s illuminate/events.
     • symfony/http-foundation → Remove (not needed in Laravel).
   • Create a Laravel-compatible SavepointCrashListener using DBAL\ConnectionEvents.
   • Test with a single transaction (e.g., a User creation with a savepoint).

2. Phase 2: Full Integration

   • Option A: Middleware Approach
     • Register a middleware to wrap DB::transaction() calls:

       public function handle($request, Closure $next) {
           DB::connection()->getDoctrineConnection()->getEventManager()->addEventListener(
               ConnectionEvents::postConnect,
               new SavepointCrashListener()
           );
           return $next($request);
       }
       

   • Option B: Doctrine Event Listener
     • Bind to postConnect or postTransaction events in AppServiceProvider:

       $this->app->booting(function () {
           DB::connection()->getDoctrineConnection()->getEventManager()->addEventListener(
               ConnectionEvents::postConnect,
               new \DualMedia\DoctrineRetryBundle\Listener\SavepointCrashListener()
           );
       });
       

   • Option C: Query Builder Hook
     • Override DB::statement() to intercept ROLLBACK TO queries (less robust).

3. Phase 3: Validation

   • Unit Tests: Mock MariaDB’s savepoint crash (simulate SQLSTATE[HY000]).
   • Load Testing: Verify no performance regression in transaction-heavy endpoints.
   • Rollback Testing: Ensure partial transactions don’t corrupt data.

Compatibility

• Doctrine Version: Tested with MariaDB/MySQL. Confirm compatibility with Laravel’s Doctrine version (e.g., doctrine/dbal:^3.0).
• Laravel Version: Target Laravel 10.x/11.x (Symfony 6.x+ compatibility).
• PHP Version: Requires PHP 8.1+ (check Laravel’s supported versions).
• Database Drivers: Ensure pdo_mysql is used (not mysqlnd or other abstractions).

Sequencing

1. Prerequisite: Install doctrine/dbal and dualmedia/doctrine-retry-bundle (if using retries).
2. Order of Operations:
   • Register the listener before any database transactions occur (e.g., in AppServiceProvider::boot()).
   • Ensure the listener runs after Doctrine’s connection is established (use postConnect event).
3. Fallback: Implement a circuit breaker (e.g., spatie/laravel-circuit-breaker) if the bundle fails to prevent crashes.

Operational Impact

Maintenance

• Vendor Lock-In: Minimal (MIT license, open-source). Risk of abandonment if the package is unmaintained (last release: 2025-09-18).
• Dependency Updates:
  • Monitor dualmedia/doctrine-retry-bundle for breaking changes.
  • Laravel’s Doctrine packages may drift from Symfony’s versions.
• Customization:
  • If the bundle’s logic is insufficient, forks may diverge from upstream.
  • Consider extracting the core logic (savepoint rollback handler) into a standalone service for easier maintenance.

Support

• Debugging:
  • Crashes may be silent (e.g., Doctrine swallows exceptions). Enable Doctrine debug mode (APP_DEBUG=true) and log ConnectionEvents.
  • Add Sentry/Monolog hooks to capture SQLSTATE[HY000] errors.
• Community:
  • No stars/dependents → limited community support. Prepare for self-service troubleshooting.
  • Engage with the author via GitHub issues for Laravel-specific guidance.
• Documentation:
  • The README is minimal. Create internal docs for:
    • How to test savepoint failures.
    • Expected performance impact.
    • Fallback procedures.

Scaling

• Performance:
  • Savepoints add overhead per transaction. Benchmark with:
    • AB or k6 to measure TPS before/after integration.
    • Focus on write-heavy endpoints (e.g., order processing).
  • Mitigation: Use sparingly (e.g., only for critical transactions).
• Horizontal Scaling:
  • Stateless middleware/listeners scale well with Laravel’s queue workers.
  • **