Add our own DB exception abstraction

Right now our API exports the Doctrine/dbal exception. As we've seen
with the dbal 3 upgrade, the leakage of 3rdparty types is problematic as
a dependency update means lots of work in apps, due to the direct
dependency of what Nextcloud ships. This breaks this dependency so that
apps only need to depend on our public API. That API can then be vendor
(db lib) agnostic and we can work around future deprecations/removals in
dbal more easily.

Right now the type of exception thrown is transported as "reason". For
the more popular types of errors we can extend the new exception class
and allow apps to catch specific errors only. Right now they have to
catch-check-rethrow. This is not ideal, but better than the dependnecy
on dbal.

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>

2 files changed, 151 insertions, 0 deletions

diff --git a/lib/public/DB/Exception.php b/lib/public/DB/Exception.php
new file mode 100644
index 00000000000..1154530e85d
--- /dev/null
+++ b/lib/public/DB/Exception.php
@@ -0,0 +1,149 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace OCP\DB;
+
+use Exception as BaseException;
+
+/**
+ * Database exception
+ *
+ * Thrown by Nextcloud's database abstraction layer. This is the base class that
+ * any specific exception will extend. Use this class in your try-catch to catch
+ * *any* error related to the database. Use any of the subclasses in the same
+ * namespace if you are only interested in specific errors.
+ *
+ * @psalm-immutable
+ * @since 21.0.0
+ */
+class Exception extends BaseException {
+
+	/**
+	 * Nextcloud lost connection to the database
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_CONNECTION_LOST = 1;
+
+	/**
+	 * A database constraint was violated
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_CONSTRAINT_VIOLATION = 2;
+
+	/**
+	 * A database object (table, column, index) already exists
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_DATABASE_OBJECT_EXISTS = 3;
+
+	/**
+	 * A database object (table, column, index) can't be found
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_DATABASE_OBJECT_NOT_FOUND = 4;
+
+	/**
+	 * The database ran into a deadlock
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_DEADLOCK = 5;
+
+	/**
+	 * The database driver encountered an issue
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_DRIVER = 6;
+
+	/**
+	 * A foreign key constraint was violated
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_FOREIGN_KEY_VIOLATION = 7;
+
+	/**
+	 * An invalid argument was passed to the database abstraction
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_INVALID_ARGUMENT = 8;
+
+	/**
+	 * A field name was invalid
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_INVALID_FIELD_NAME = 9;
+
+	/**
+	 * A name in the query was ambiguous
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_NON_UNIQUE_FIELD_NAME = 10;
+
+	/**
+	 * A not null contraint was violated
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_NOT_NULL_CONSTRAINT_VIOLATION = 11;
+
+	/**
+	 * A generic server error was encountered
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_SERVER = 12;
+
+	/**
+	 * A syntax error was reported by the server
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_SYNTAX_ERROR = 13;
+
+	/**
+	 * A unique constraint was violated
+	 *
+	 * @since 21.0.0
+	 */
+	public const REASON_UNIQUE_CONSTRAINT_VIOLATION = 14;
+
+	/**
+	 * @return int|null
+	 * @psalm-return Exception::REASON_*
+	 * @since 21.0.0
+	 */
+	public function getReason(): ?int {
+		return null;
+	}
+}
diff --git a/lib/public/DB/QueryBuilder/IQueryBuilder.php b/lib/public/DB/QueryBuilder/IQueryBuilder.php
index 8fcbd6c3276..24de7b4ce60 100644
--- a/lib/public/DB/QueryBuilder/IQueryBuilder.php
+++ b/lib/public/DB/QueryBuilder/IQueryBuilder.php
@@ -29,6 +29,7 @@
 namespace OCP\DB\QueryBuilder;
 
 use Doctrine\DBAL\Connection;
+use OCP\DB\Exception;
 use OCP\DB\IResult;
 
 /**
@@ -154,6 +155,7 @@ interface IQueryBuilder {
 	 *          to bridge old code to the new API
 	 *
 	 * @return IResult|int
+	 * @throws Exception since 21.0.0
 	 * @since 8.2.0
 	 */
 	public function execute();