no issue - error handling

docs/.vitepress/config.mts

@@ -55,6 +55,7 @@ export default defineConfig({
               { text: 'Doctrine DBAL setup', link: '/introduction/getting-started#doctrine-dbal-setup' },
               { text: 'PDO setup', link: '/introduction/getting-started#pdo-setup' },
               { text: 'Symfony setup', link: '/introduction/getting-started#symfony-setup' },
+              { text: 'Error handling', link: '/bridges/error' },
             ]
           },
           { text: 'Samples usages', link: '/introduction/usage' },

src/Bridge/AbstractBridge.php

@@ -34,13 +34,25 @@ abstract class AbstractBridge extends DefaultQueryBuilder implements Bridge
     private ?string $serverVersion = null;
     private bool $serverVersionLookekUp = false;
     private ?string $serverFlavor = null;
+    private ?ErrorConverter $errorConverter = null;
 
     public function __construct(?ConverterPluginRegistry $converterPluginRegistry = null)
     {
         $this->converterPluginRegistry = $converterPluginRegistry;
         $this->setQueryExecutor($this);
     }
 
+    /**
+     * Disable error converter. Must be called prior to initilization.
+     */
+    public function disableErrorConverter(): bool
+    {
+        if ($this->errorConverter) {
+            throw new QueryBuilderError("Bridge is already initialized, configuration must happend before it gets used.");
+        }
+        $this->errorConverter = new PassthroughErrorConverter();
+    }
+
     /**
      * @internal
      *   For dependency injection only.
@@ -82,6 +94,31 @@ public function getServerName(): ?string
         return $this->serverName;
     }
 
+    /**
+     * Get error converter.
+     */
+    protected function getErrorConverter(): ErrorConverter
+    {
+        return $this->errorConverter ??= $this->createErrorConverter();
+    }
+
+    /**
+     * @internal
+     *    For dependency injection only.
+     */
+    public function setErrorConverter(ErrorConverter $errorConverter): void
+    {
+        $this->errorConverter = $errorConverter;
+    }
+
+    /**
+     * Please override.
+     */
+    protected function createErrorConverter(): ErrorConverter
+    {
+        return new PassthroughErrorConverter();
+    }
+
     /**
      * Please override.
      */
@@ -199,7 +236,11 @@ public function executeQuery(string|Expression $expression = null, mixed $argume
 
         $prepared = $this->getWriter()->prepare($expression);
 
-        return $this->doExecuteQuery($prepared->toString(), $prepared->getArguments()->getAll());
+        try {
+            return $this->doExecuteQuery($prepared->toString(), $prepared->getArguments()->getAll());
+        } catch (\Throwable $e) {
+            throw $this->getErrorConverter()->convertError($e);
+        }
     }
 
     /**
@@ -223,7 +264,11 @@ public function executeStatement(string|Expression $expression = null, mixed $ar
 
         $prepared = $this->getWriter()->prepare($expression);
 
-        return $this->doExecuteStatement($prepared->toString(), $prepared->getArguments()->getAll());
+        try {
+            return $this->doExecuteStatement($prepared->toString(), $prepared->getArguments()->getAll());
+        } catch (\Throwable $e) {
+            throw $this->getErrorConverter()->convertError($e);
+        }
     }
 
     /**

src/Bridge/Bridge.php

@@ -10,6 +10,11 @@
 
 interface Bridge extends QueryExecutor, QueryBuilder
 {
+    /**
+     * Disable error converter. Must be called prior to initilization.
+     */
+    public function disableErrorConverter(): bool;
+
     /**
      * Get server name.
      */

src/Bridge/Doctrine/DoctrineQueryBuilder.php

@@ -6,13 +6,15 @@
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
-use MakinaCorpus\QueryBuilder\Platform;
 use MakinaCorpus\QueryBuilder\Bridge\AbstractBridge;
+use MakinaCorpus\QueryBuilder\Bridge\Doctrine\ErrorConverter\DoctrineErrorConverter;
 use MakinaCorpus\QueryBuilder\Bridge\Doctrine\Escaper\DoctrineEscaper;
 use MakinaCorpus\QueryBuilder\Bridge\Doctrine\Escaper\DoctrineMySQLEscaper;
+use MakinaCorpus\QueryBuilder\Bridge\ErrorConverter;
 use MakinaCorpus\QueryBuilder\Converter\Converter;
 use MakinaCorpus\QueryBuilder\Error\QueryBuilderError;
 use MakinaCorpus\QueryBuilder\Escaper\Escaper;
+use MakinaCorpus\QueryBuilder\Platform;
 use MakinaCorpus\QueryBuilder\Result\IterableResult;
 use MakinaCorpus\QueryBuilder\Result\Result;
 use MakinaCorpus\QueryBuilder\Writer\Writer;
@@ -30,6 +32,14 @@ public function __construct(
         $this->connection = $connection;
     }
 
+    /**
+     * Please override.
+     */
+    protected function createErrorConverter(): ErrorConverter
+    {
+        return new DoctrineErrorConverter();
+    }
+
     /**
      * {@inheritdoc}
      */

src/Bridge/Doctrine/ErrorConverter/DoctrineErrorConverter.php

@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MakinaCorpus\QueryBuilder\Bridge\Doctrine\ErrorConverter;
+
+use Doctrine\DBAL\ConnectionException;
+use Doctrine\DBAL\Exception\ConnectionLost;
+use Doctrine\DBAL\Exception\ConstraintViolationException;
+use Doctrine\DBAL\Exception\DatabaseDoesNotExist;
+use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
+use Doctrine\DBAL\Exception\InvalidFieldNameException;
+use Doctrine\DBAL\Exception\NonUniqueFieldNameException;
+use Doctrine\DBAL\Exception\NotNullConstraintViolationException;
+use Doctrine\DBAL\Exception\TableNotFoundException;
+use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
+use Doctrine\DBAL\Schema\Exception\ColumnDoesNotExist;
+use Doctrine\DBAL\Schema\Exception\TableDoesNotExist;
+use MakinaCorpus\QueryBuilder\Bridge\ErrorConverter;
+use MakinaCorpus\QueryBuilder\Error\Bridge\AmbiguousIdentifierError;
+use MakinaCorpus\QueryBuilder\Error\Bridge\ColumnDoesNotExistError;
+use MakinaCorpus\QueryBuilder\Error\Bridge\ConstraintViolationError;
+use MakinaCorpus\QueryBuilder\Error\Bridge\DatabaseObjectDoesNotExistError;
+use MakinaCorpus\QueryBuilder\Error\Bridge\ForeignKeyConstraintViolationError;
+use MakinaCorpus\QueryBuilder\Error\Bridge\NotNullConstraintViolationError;
+use MakinaCorpus\QueryBuilder\Error\Bridge\TableDoesNotExistError;
+use MakinaCorpus\QueryBuilder\Error\Bridge\UnableToConnectError;
+use MakinaCorpus\QueryBuilder\Error\Bridge\UniqueConstraintViolationError;
+use MakinaCorpus\QueryBuilder\Bridge\Pdo\ErrorConverter\PdoSQLiteErrorConverter;
+
+class DoctrineErrorConverter implements ErrorConverter
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function convertError(\Throwable $error, ?string $sql = null, ?string $message = null): \Throwable
+    {
+        $message ??= $error->getMessage();
+
+        if ($error instanceof InvalidFieldNameException || $error instanceof ColumnDoesNotExist) {
+            return new ColumnDoesNotExistError($message, $error->getCode(), $error);
+        }
+
+        if ($error instanceof DatabaseDoesNotExist) {
+            return new DatabaseObjectDoesNotExistError($message, $error->getCode(), $error);
+        }
+
+        if ($error instanceof ForeignKeyConstraintViolationException) {
+            return new ForeignKeyConstraintViolationError($message, $error->getCode(), $error);
+        }
+
+        if ($error instanceof NotNullConstraintViolationException) {
+            return new NotNullConstraintViolationError($message, $error->getCode(), $error);
+        }
+
+        if ($error instanceof TableDoesNotExist || $error instanceof TableNotFoundException) {
+            return new TableDoesNotExistError($message, $error->getCode(), $error);
+        }
+
+        /* if ($error instanceof Foo) {
+            return new TransactionDeadlockError();
+        } */
+
+        /* if ($error instanceof Foo) {
+            return new TransactionLockWaitTimeoutError();
+        } */
+
+        if ($error instanceof ConnectionException || $error instanceof ConnectionLost) {
+            return new UnableToConnectError($message, $error->getCode(), $error);
+        }
+
+        if ($error instanceof UniqueConstraintViolationException) {
+            return new UniqueConstraintViolationError($message, $error->getCode(), $error);
+        }
+
+        /*
+         * More generic errors after.
+         */
+
+        if ($error instanceof NonUniqueFieldNameException) {
+            return new AmbiguousIdentifierError();
+        }
+
+        /* if ($error instanceof Foo) {
+            return new TransactionFailedError();
+        } */
+
+        if ($error instanceof ConstraintViolationException) {
+            return new ConstraintViolationError($message, $error->getCode(), $error);
+        }
+
+        // Provide fallbacks for SQLite, because DBAL don't catch them all.
+        return PdoSQLiteErrorConverter::createErrorFromMessage($error, $sql, $message);
+    }
+}

src/Bridge/ErrorConverter.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MakinaCorpus\QueryBuilder\Bridge;
+
+interface ErrorConverter
+{
+    /**
+     * Convert underlaying connector errors to a common error.
+     *
+     * @param \Throwable $error
+     *   Original error from driver.
+     * @param null|string $sqlQuery
+     *   The raw SQL query that is the subject of this error.
+     * @param null|string $message
+     *   Overriden error message, if any.
+     */
+    public function convertError(\Throwable $error, ?string $sql = null, ?string $message = null): \Throwable;
+}

src/Bridge/PassthroughErrorConverter.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MakinaCorpus\QueryBuilder\Bridge;
+
+/**
+ * Implementation for when the error handling is disabled.
+ *
+ * Useful when configured over a doctrine/dbal bridge in Symfony context and
+ * you want the Query Builder to be absolutely transparently integrated with
+ * it. It's also true for other bridges contextes.
+ */
+class PassthroughErrorConverter implements ErrorConverter
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function convertError(\Throwable $error, ?string $sql = null, ?string $message = null): \Throwable
+    {
+        return $error;
+    }
+}