feat(entity): Add support for composite primary key

Assisted-by: ClaudeCode:claude-opus-5
Signed-off-by: Carl Schwan <carl@carlschwan.eu>

Author: CarlSchwan

apps/comments/composer/composer/installed.php

@@ -3,7 +3,7 @@
         'name' => '__root__',
         'pretty_version' => 'dev-master',
         'version' => 'dev-master',
-        'reference' => '85618b795280107ce542bff646bc0957bc09a452',
+        'reference' => 'b1797842784b250fb01ed5e3bf130705eb94751b',
         'type' => 'library',
         'install_path' => __DIR__ . '/../',
         'aliases' => array(),
@@ -13,7 +13,7 @@
         '__root__' => array(
             'pretty_version' => 'dev-master',
             'version' => 'dev-master',
-            'reference' => '85618b795280107ce542bff646bc0957bc09a452',
+            'reference' => 'b1797842784b250fb01ed5e3bf130705eb94751b',
             'type' => 'library',
             'install_path' => __DIR__ . '/../',
             'aliases' => array(),

lib/private/AppFramework/ORM/EntityInfo.php

@@ -33,7 +33,13 @@ final class EntityInfo {
 	/** @var \ReflectionClass<T> */
 	public readonly \ReflectionClass $reflection;
 
-	public ?\ReflectionProperty $idProperty = null;
+	/**
+	 * All properties carrying an #[Id] attribute, in declaration order. More than one entry
+	 * means the entity has a composite primary key.
+	 *
+	 * @var list<\ReflectionProperty>
+	 */
+	public array $idProperties = [];
 
 	/**
 	 * @var list<PropertyAttributes> $propertiesAttributes
@@ -68,7 +74,7 @@ public function __construct(
 					$this->mappingPropertyToColumn[$property->getName()] = $instance->name;
 				} elseif ($instance instanceof Id) {
 					$propertyAttributes->id = $instance;
-					$this->idProperty = $property;
+					$this->idProperties[] = $property;
 				} elseif ($instance instanceof OneToOne) {
 					$propertyAttributes->oneToOne = $instance;
 				} elseif ($instance instanceof ManyToOne) {
@@ -96,17 +102,37 @@ public function __construct(
 			$this->propertiesAttributes[] = $propertyAttributes;
 		}
 
-		if (!$this->idProperty instanceof \ReflectionProperty) {
+		if ($this->idProperties === []) {
 			throw new \RuntimeException($this->entityClass . ' does not have a primary key. This is not supported for repositories backed tables.');
 		}
 	}
 
-	public function getIdProperty(): \ReflectionProperty {
-		if (!$this->idProperty instanceof \ReflectionProperty) {
-			throw new \LogicException('Unreachable: the constructor already guarantees idProperty is set.');
+	/**
+	 * @return non-empty-list<\ReflectionProperty>
+	 */
+	public function getIdProperties(): array {
+		if ($this->idProperties === []) {
+			throw new \LogicException('Unreachable: the constructor already guarantees idProperties is not empty.');
+		}
+
+		return $this->idProperties;
+	}
+
+	public function hasCompositeIdProperty(): bool {
+		return count($this->idProperties) > 1;
+	}
+
+	/**
+	 * Convenience accessor for code paths (e.g. relation joins) that only support entities with
+	 * a single-column primary key.
+	 */
+	public function getSingleIdProperty(): \ReflectionProperty {
+		$idProperties = $this->getIdProperties();
+		if (count($idProperties) > 1) {
+			throw new \LogicException($this->entityClass . ' has a composite primary key, which is not supported here.');
 		}
 
-		return $this->idProperty;
+		return $idProperties[0];
 	}
 
 	/**

lib/private/AppFramework/ORM/EntityManager.php

@@ -70,7 +70,8 @@ public function insert(object $entity): object {
 		$entityInfo = $this->getEntityInfo($entity::class);
 		$insert = $this->connection->getQueryBuilder();
 
-		$isSnowflake = false;
+		$isComposite = $entityInfo->hasCompositeIdProperty();
+		$autoIncrementProperty = null;
 		$values = [];
 
 		foreach ($entityInfo->propertiesAttributes as $propertyAttributes) {
@@ -80,12 +81,33 @@ public function insert(object $entity): object {
 				if ($generatorClass) {
 					if ($generatorClass === ISnowflakeGenerator::class) {
 						$generator = Server::get($generatorClass);
-						$isSnowflake = true;
 						$values[$propertyAttributes->column->name] = $generator->nextId();
 						$property->setValue($entity, $insert->createNamedParameter($values[$propertyAttributes->column->name]));
 					}
+
+					continue;
 				}
 
+				if ($isComposite) {
+					// A composite primary key can't rely on a single autoincrement column: every
+					// part must already be set on the entity (e.g. a foreign key id, or a value
+					// assigned by the caller) before insert() is called.
+					/** @var mixed $value */
+					$value = $property->getValue($entity);
+					if ($value === null) {
+						throw new \LogicException($entity::class . '::' . $property->getName() . ' is part of a composite primary key and must be set before insert(); it cannot rely on DB autoincrement.');
+					}
+					if (!is_string($value) && !is_int($value)) {
+						throw new \LogicException($entity::class . '::' . $property->getName() . ' is part of a composite primary key and must be set to a int or string before insert();.');
+					}
+
+					$type = $this->getParameterType($propertyAttributes->column->type, false);
+					$values[$propertyAttributes->column->name] = $insert->createNamedParameter($value, $type);
+					continue;
+				}
+
+				// Single autoincrement primary key: let the DB generate it, then read it back below.
+				$autoIncrementProperty = $property;
 				continue;
 			}
 
@@ -106,7 +128,7 @@ public function insert(object $entity): object {
 				if ($targetEntity === null) {
 					$values[$joinColumn->name] = $insert->createNamedParameter(null);
 				} else {
-					$values[$joinColumn->name] = $insert->createNamedParameter($targetEntityInfo->getIdProperty()->getValue($targetEntity));
+					$values[$joinColumn->name] = $insert->createNamedParameter($targetEntityInfo->getSingleIdProperty()->getValue($targetEntity));
 				}
 
 				continue;
@@ -122,8 +144,8 @@ public function insert(object $entity): object {
 			->values($values)
 			->executeStatement();
 
-		if (!$isSnowflake) {
-			$entityInfo->getIdProperty()->setValue($entity, $insert->getLastInsertId());
+		if ($autoIncrementProperty !== null) {
+			$autoIncrementProperty->setValue($entity, $insert->getLastInsertId());
 		}
 
 		return $entity;
@@ -151,7 +173,7 @@ public function update(object $entity): object {
 					throw new \LogicException('Trying to update an entity with no primary key set.');
 				}
 
-				$update->andWhere($update->expr()->eq($entityInfo->mappingPropertyToColumn[$entityInfo->getIdProperty()->getName()], $update->createNamedParameter($property->getValue($entity))));
+				$update->andWhere($update->expr()->eq($propertyAttributes->column->name, $update->createNamedParameter($value)));
 				// don't update the id
 				continue;
 			}
@@ -169,7 +191,7 @@ public function update(object $entity): object {
 				if ($targetEntity === null) {
 					$update->set($joinColumn->name, $update->createNamedParameter(null));
 				} else {
-					$update->set($joinColumn->name, $update->createNamedParameter($targetEntityInfo->getIdProperty()->getValue($targetEntity)));
+					$update->set($joinColumn->name, $update->createNamedParameter($targetEntityInfo->getSingleIdProperty()->getValue($targetEntity)));
 				}
 
 				continue;
@@ -266,11 +288,19 @@ public function createTable(string $entityClass, SchemaWrapper $schema): void {
 
 		$table = $schema->createTable($entityInfo->tableName);
 
+		/** @var list<string> $idColumns */
+		$idColumns = [];
 		foreach ($entityInfo->propertiesAttributes as $propertyAttributes) {
-			$this->createProperty($propertyAttributes, $table);
+			$this->createProperty($entityInfo, $propertyAttributes, $table);
+
+			if ($propertyAttributes->id instanceof Id && $propertyAttributes->column instanceof Column) {
+				$idColumns[] = $propertyAttributes->column->name;
+			}
 
 			$this->createRelationColumn($propertyAttributes, $table, $schema);
 		}
+
+		$table->setPrimaryKey($idColumns);
 	}
 
 	/**
@@ -281,7 +311,7 @@ public function dropTable(string $entityClass, string $prefix): void {
 		$this->connection->dropTable($prefix . $entityInfo->tableName);
 	}
 
-	private function createProperty(PropertyAttributes $attributes, Table $table): void {
+	private function createProperty(EntityInfo $entityInfo, PropertyAttributes $attributes, Table $table): void {
 		if (!$attributes->column instanceof Column) {
 			return;
 		}
@@ -299,15 +329,12 @@ private function createProperty(PropertyAttributes $attributes, Table $table): v
 			$options['default'] = $columnAttribute->default;
 		}
 
-		if ($attributes->id instanceof Id && $attributes->id->generatorClass === null) {
+		// A composite primary key can't rely on a single autoincrement column; see insert().
+		if ($attributes->id instanceof Id && $attributes->id->generatorClass === null && !$entityInfo->hasCompositeIdProperty()) {
 			$options['autoincrement'] = true;
 		}
 
 		$table->addColumn($columnAttribute->name, $columnAttribute->type, $options);
-
-		if ($attributes->id instanceof Id) {
-			$table->setPrimaryKey([$columnAttribute->name]);
-		}
 	}
 
 	private function createRelationColumn(PropertyAttributes $attributes, Table $table, SchemaWrapper $schema): void {

lib/public/AppFramework/ORM/Attribute/Id.php

@@ -12,7 +12,7 @@
 use OCP\Snowflake\ISnowflakeGenerator;
 
 /**
- * Attribute for marking a column as a primary id.
+ * Attribute for marking a column as (part of) the primary key.
  *
  * ```php
  * #[Entity(name: 'my_entity']
@@ -23,6 +23,23 @@
  * }
  * ```
  *
+ * Applying #[Id] to more than one property declares a composite primary key. In that case every
+ * id property must have its value set before calling `insert()` (via `generatorClass`, or
+ * assigned by the caller), since a composite key cannot rely on a single autoincrement column:
+ *
+ * ```php
+ * #[Entity(name: 'my_join_entity']
+ * final class MyJoinEntity {
+ *     #[Id]
+ *     #[Column(name: 'left_id', type: Types::BIGINT)]
+ *     public int $leftId;
+ *
+ *     #[Id]
+ *     #[Column(name: 'right_id', type: Types::BIGINT)]
+ *     public int $rightId;
+ * }
+ * ```
+ *
  * @since 35.0.0
  */
 #[Attribute(Attribute::TARGET_PROPERTY)]

lib/public/AppFramework/ORM/Repository.php

@@ -12,7 +12,6 @@
 use OC\AppFramework\ORM\PropertyAttributes;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Db\MultipleObjectsReturnedException;
-use OCP\AppFramework\ORM\Attribute\Id;
 use OCP\DB\Exception;
 use OCP\DB\QueryBuilder\IQueryBuilder;
 use OCP\DB\Types;
@@ -84,17 +83,9 @@ private function hydrateRow(string $entityClass, mixed $row): object {
 				$type = Types::STRING;
 			}
 
-			if ($column === $entityInfo->getIdProperty()->getName()) {
-				$ids = $entityInfo->getIdProperty()->getAttributes(Id::class, \ReflectionAttribute::IS_INSTANCEOF);
-				$id = array_shift($ids);
-				if ($id === null) {
-					throw new \LogicException('Unreachable: the id property is missing its #[Id] attribute.');
-				}
-
-				if ($id->newInstance()->generatorClass !== null) {
-					$entity->$property = (string)$value;
-					continue;
-				}
+			if ($this->isGeneratedIdColumn($entityInfo, $column)) {
+				$entity->$property = (string)$value;
+				continue;
 			}
 
 			/** @psalm-suppress DeprecatedConstant Types::JSON is only discouraged in WHERE clauses; mapping it is still supported. */
@@ -153,6 +144,16 @@ private function hydrateRow(string $entityClass, mixed $row): object {
 		return $entity;
 	}
 
+	private function isGeneratedIdColumn(EntityInfo $entityInfo, string $column): bool {
+		foreach ($entityInfo->propertiesAttributes as $propertyAttributes) {
+			if ($propertyAttributes->id !== null && $propertyAttributes->column?->name === $column) {
+				return $propertyAttributes->id->generatorClass !== null;
+			}
+		}
+
+		return false;
+	}
+
 	/**
 	 * Builds a select query resolving OneToOne and ManyToOne relations via a LEFT JOIN.
 	 * Columns are aliased `e_<column>` (main entity) and `r<index>_<column>` (each relation)
@@ -274,7 +275,7 @@ private function mapJoinedRowToEntity(array $relations, mixed $row): object {
 		foreach ($relations as $alias => $relation) {
 			$propertyName = $relation['attributes']->property->getName();
 			$targetEntityInfo = $relation['entityInfo'];
-			$idColumn = $targetEntityInfo->mappingPropertyToColumn[$targetEntityInfo->getIdProperty()->getName()];
+			$idColumn = $targetEntityInfo->mappingPropertyToColumn[$targetEntityInfo->getSingleIdProperty()->getName()];
 			$relationRow = $relationRows[$alias] ?? [];
 
 			if (($relationRow[$idColumn] ?? null) === null) {