Table: document thrown exceptions

src/Scaffolding/TableImplementation.php

@@ -16,8 +16,10 @@ use Grifart\Tables\ColumnNotFound;
 use Grifart\Tables\Conditions\Condition;
 use Grifart\Tables\DefaultOrExistingValue;
 use Grifart\Tables\Expression;
+use Grifart\Tables\GivenSearchCriteriaHaveNotMatchedAnyRows;
 use Grifart\Tables\RowNotFound;
 use Grifart\Tables\OrderBy\OrderBy;
+use Grifart\Tables\RowWithGivenPrimaryKeyAlreadyExists;
 use Grifart\Tables\Table;
 use Grifart\Tables\TableManager;
 use Grifart\Tables\TooManyRowsFound;
@@ -249,9 +251,13 @@ final class TableImplementation implements Capability
 			$method->addBody('return $modifications;');
 		}
 
+		$namespace->addUse(RowWithGivenPrimaryKeyAlreadyExists::class);
+		$namespace->addUse(GivenSearchCriteriaHaveNotMatchedAnyRows::class);
 
 		$classType->addMethod('save')
 			->addComment('@deprecated')
+			->addComment('@throws RowWithGivenPrimaryKeyAlreadyExists')
+			->addComment('@throws GivenSearchCriteriaHaveNotMatchedAnyRows')
 			->setReturnType('void')
 			->setParameters([
 				(new Code\Parameter('changes'))->setType($this->modificationClass)
@@ -261,6 +267,7 @@ final class TableImplementation implements Capability
 			);
 
 		$classType->addMethod('insert')
+			->addComment('@throws RowWithGivenPrimaryKeyAlreadyExists')
 			->setReturnType('void')
 			->setParameters([
 				(new Code\Parameter('changes'))->setType($this->modificationClass),
@@ -270,6 +277,7 @@ final class TableImplementation implements Capability
 			);
 
 		$classType->addMethod('update')
+			->addComment('@throws GivenSearchCriteriaHaveNotMatchedAnyRows')
 			->setReturnType('void')
 			->setParameters([
 				(new Code\Parameter('changes'))->setType($this->modificationClass),
@@ -279,6 +287,8 @@ final class TableImplementation implements Capability
 			);
 
 		$classType->addMethod('insertOrUpdate')
+			->addComment('@throws RowWithGivenPrimaryKeyAlreadyExists')
+			->addComment('@throws GivenSearchCriteriaHaveNotMatchedAnyRows')
 			->setReturnType('void')
 			->setParameters([
 				(new Code\Parameter('changes'))->setType($this->modificationClass),

src/TableManager.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Grifart\Tables;
 
 use Dibi\Connection;
+use Dibi\UniqueConstraintViolationException;
 use Grifart\Tables\Conditions\Composite;
 use Grifart\Tables\Conditions\Condition;
 use Grifart\Tables\OrderBy\OrderBy;
@@ -26,18 +27,25 @@ final class TableManager
 	 * @template TableType of Table
 	 * @param TableType $table
 	 * @param Modifications<TableType> $changes
+	 * @throws RowWithGivenPrimaryKeyAlreadyExists
 	 */
 	public function insert(Table $table, Modifications $changes): void
 	{
 		\assert($changes->getPrimaryKey() === NULL);
-		$this->connection->query(
-			'INSERT',
-			'INTO %n.%n', $table::getSchema(), $table::getTableName(),
-			map(
-				$changes->getModifications(),
-				static fn(mixed $value, string $columnName) => $value !== null ? $table->getTypeOf($columnName)->toDatabase($value) : null,
-			),
-		);
+
+		try {
+			$this->connection->query(
+				'INSERT',
+				'INTO %n.%n', $table::getSchema(), $table::getTableName(),
+				map(
+					$changes->getModifications(),
+					static fn(mixed $value, string $columnName) => $value !== null ? $table->getTypeOf($columnName)->toDatabase($value) : null,
+				),
+			);
+		} catch (UniqueConstraintViolationException $e) {
+			throw new RowWithGivenPrimaryKeyAlreadyExists(previous: $e);
+		}
+
 		\assert($this->connection->getAffectedRows() === 1);
 	}
 
@@ -177,6 +185,7 @@ final class TableManager
 	 * @template TableType of Table
 	 * @param TableType $table
 	 * @param Modifications<TableType> $changes
+	 * @throws RowWithGivenPrimaryKeyAlreadyExists
 	 * @throws GivenSearchCriteriaHaveNotMatchedAnyRows
 	 */
 	public function save(Table $table, Modifications $changes): void {

src/exceptions.php

@@ -66,6 +66,6 @@ final class ColumnNotFound extends UsageException {
 }
 
 final class GivenSearchCriteriaHaveNotMatchedAnyRows extends RuntimeException {}
-
+final class RowWithGivenPrimaryKeyAlreadyExists extends RuntimeException {}
 final class RowNotFound extends RuntimeException {}
 final class TooManyRowsFound extends UsageException {}

tests/Fixtures/PackagesTable.php

@@ -14,8 +14,10 @@ use Grifart\Tables\ColumnNotFound;
 use Grifart\Tables\Conditions\Condition;
 use Grifart\Tables\DefaultOrExistingValue;
 use Grifart\Tables\Expression;
+use Grifart\Tables\GivenSearchCriteriaHaveNotMatchedAnyRows;
 use Grifart\Tables\OrderBy\OrderBy;
 use Grifart\Tables\RowNotFound;
+use Grifart\Tables\RowWithGivenPrimaryKeyAlreadyExists;
 use Grifart\Tables\Table;
 use Grifart\Tables\TableManager;
 use Grifart\Tables\TooManyRowsFound;
@@ -178,6 +180,8 @@ final class PackagesTable implements Table
 
 	/**
 	 * @deprecated
+	 * @throws RowWithGivenPrimaryKeyAlreadyExists
+	 * @throws GivenSearchCriteriaHaveNotMatchedAnyRows
 	 */
 	public function save(PackageModifications $changes): void
 	{
@@ -185,18 +189,28 @@ final class PackagesTable implements Table
 	}
 
 
+	/**
+	 * @throws RowWithGivenPrimaryKeyAlreadyExists
+	 */
 	public function insert(PackageModifications $changes): void
 	{
 		$this->tableManager->insert($this, $changes);
 	}
 
 
+	/**
+	 * @throws GivenSearchCriteriaHaveNotMatchedAnyRows
+	 */
 	public function update(PackageModifications $changes): void
 	{
 		$this->tableManager->update($this, $changes);
 	}
 
 
+	/**
+	 * @throws RowWithGivenPrimaryKeyAlreadyExists
+	 * @throws GivenSearchCriteriaHaveNotMatchedAnyRows
+	 */
 	public function insertOrUpdate(PackageModifications $changes): void
 	{
 		$this->tableManager->save($this, $changes);

tests/Fixtures/TestsTable.php

@@ -14,8 +14,10 @@ use Grifart\Tables\ColumnNotFound;
 use Grifart\Tables\Conditions\Condition;
 use Grifart\Tables\DefaultOrExistingValue;
 use Grifart\Tables\Expression;
+use Grifart\Tables\GivenSearchCriteriaHaveNotMatchedAnyRows;
 use Grifart\Tables\OrderBy\OrderBy;
 use Grifart\Tables\RowNotFound;
+use Grifart\Tables\RowWithGivenPrimaryKeyAlreadyExists;
 use Grifart\Tables\Table;
 use Grifart\Tables\TableManager;
 use Grifart\Tables\TooManyRowsFound;
@@ -176,6 +178,8 @@ final class TestsTable implements Table
 
 	/**
 	 * @deprecated
+	 * @throws RowWithGivenPrimaryKeyAlreadyExists
+	 * @throws GivenSearchCriteriaHaveNotMatchedAnyRows
 	 */
 	public function save(TestModifications $changes): void
 	{
@@ -183,18 +187,28 @@ final class TestsTable implements Table
 	}
 
 
+	/**
+	 * @throws RowWithGivenPrimaryKeyAlreadyExists
+	 */
 	public function insert(TestModifications $changes): void
 	{
 		$this->tableManager->insert($this, $changes);
 	}
 
 
+	/**
+	 * @throws GivenSearchCriteriaHaveNotMatchedAnyRows
+	 */
 	public function update(TestModifications $changes): void
 	{
 		$this->tableManager->update($this, $changes);
 	}
 
 
+	/**
+	 * @throws RowWithGivenPrimaryKeyAlreadyExists
+	 * @throws GivenSearchCriteriaHaveNotMatchedAnyRows
+	 */
 	public function insertOrUpdate(TestModifications $changes): void
 	{
 		$this->tableManager->save($this, $changes);