feat: implement distributing partitioned queries over multiple shards

Signed-off-by: Robin Appelman <robin@icewind.nl>

3 files changed, 71 insertions, 0 deletions

diff --git a/lib/public/DB/QueryBuilder/IQueryBuilder.php b/lib/public/DB/QueryBuilder/IQueryBuilder.php
index 129787fa9c4..048de26c22a 100644
--- a/lib/public/DB/QueryBuilder/IQueryBuilder.php
+++ b/lib/public/DB/QueryBuilder/IQueryBuilder.php
@@ -1010,6 +1010,15 @@ interface IQueryBuilder {
 	public function getTableName($table);
 
 	/**
+	 * Returns the table name with database prefix as needed by the implementation
+	 *
+	 * @param string $table
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function prefixTableName(string $table): string;
+
+	/**
 	 * Returns the column name quoted and with table alias prefix as needed by the implementation
 	 *
 	 * @param string $column
@@ -1020,6 +1029,24 @@ interface IQueryBuilder {
 	public function getColumnName($column, $tableAlias = '');
 
 	/**
+	 * Provide a hint for the shard key for queries where this can't be detected otherwise
+	 *
+	 * @param string $column
+	 * @param mixed $value
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function hintShardKey(string $column, mixed $value);
+
+	/**
+	 * Set the query to run across all shards if sharding is enabled.
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function runAcrossAllShards();
+
+	/**
 	 * Get a list of column names that are expected in the query output
 	 *
 	 * @return array
diff --git a/lib/public/DB/QueryBuilder/Sharded/IShardMapper.php b/lib/public/DB/QueryBuilder/Sharded/IShardMapper.php
new file mode 100644
index 00000000000..fa00fb68719
--- /dev/null
+++ b/lib/public/DB/QueryBuilder/Sharded/IShardMapper.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Robin Appelman <robin@icewind.nl>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\DB\QueryBuilder\Sharded;
+
+/**
+ * Implementation of logic of mapping shard keys to shards.
+ * @since 30.0.0
+ */
+interface IShardMapper {
+	/**
+	 * Get the shard number for a given shard key and total shard count
+	 *
+	 * @param int $key
+	 * @param int $count
+	 * @return int
+	 * @since 30.0.0
+	 */
+	public function getShardForKey(int $key, int $count): int;
+}
diff --git a/lib/public/IDBConnection.php b/lib/public/IDBConnection.php
index 09bd1a564cd..7ef46ed0609 100644
--- a/lib/public/IDBConnection.php
+++ b/lib/public/IDBConnection.php
@@ -11,6 +11,8 @@
 namespace OCP;
 
 use Doctrine\DBAL\Schema\Schema;
+use OC\DB\QueryBuilder\Sharded\CrossShardMoveHelper;
+use OC\DB\QueryBuilder\Sharded\ShardDefinition;
 use OCP\DB\Exception;
 use OCP\DB\IPreparedStatement;
 use OCP\DB\IResult;
@@ -345,4 +347,21 @@ interface IDBConnection {
 	 * @return self::PLATFORM_MYSQL|self::PLATFORM_ORACLE|self::PLATFORM_POSTGRES|self::PLATFORM_SQLITE
 	 */
 	public function getDatabaseProvider(): string;
+
+	/**
+	 * Get the shard definition by name, if configured
+	 *
+	 * @param string $name
+	 * @return ShardDefinition|null
+	 * @since 30.0.0
+	 */
+	public function getShardDefinition(string $name): ?ShardDefinition;
+
+	/**
+	 * Get a helper class for implementing cross-shard moves
+	 *
+	 * @return CrossShardMoveHelper
+	 * @since 30.0.0
+	 */
+	public function getCrossShardMoveHelper(): CrossShardMoveHelper;
 }