feat(database): add option to get underlying query for property relation

docs/1-essentials/03-database.md

@@ -757,6 +757,43 @@ query(model: Author::class)->delete()->whereDoesntHave(relation: 'books')->execu
 query(model: Author::class)->update(verified: true)->whereHas(relation: 'books')->execute();
 ```
 
+### Querying relation properties
+
+While the global `query(Model::class)` function creates a query builder for any model, models using the `IsDatabaseModel` trait also have a `query()` method that returns a query builder scoped to a specific relation. The returned `QueryBuilder` is pre-filtered to only include records belonging to that model:
+
+```php
+// Select with constraints
+$books = $author->query('books')->select()->whereField(field: 'title', value: 'Timeline Taxi')->all();
+$books = $author->query('books')->select()->limit(limit: 5)->all();
+
+// Count related records
+$count = $author->query('books')->count()->execute();
+
+// Update scoped to relation
+$author->query('books')->update(title: 'Updated')->execute();
+
+// Delete scoped to relation
+$author->query('books')->delete()->execute();
+```
+
+The `query()` method works with all relation types:
+
+```php
+// HasMany / HasOne — simple FK on related table
+$author->query('books')->select()->all();
+$book->query('isbn')->select()->first();
+
+// BelongsTo — subquery through owner's FK
+$book->query('author')->select()->first();
+
+// HasManyThrough / HasOneThrough — subquery through intermediate table
+$tag->query('reviewers')->select()->all();
+$tag->query('topReviewer')->select()->first();
+
+// BelongsToMany — subquery through pivot table
+$tag->query('books')->select()->all();
+```
+
 ## Migrations
 
 When persisting objects to the database, a table is required to store the data. A migration is a file that instructs the framework how to manage the database schema.

packages/database/src/BelongsTo.php

@@ -6,12 +6,15 @@
 
 use Attribute;
 use Tempest\Database\Builder\ModelInspector;
+use Tempest\Database\Builder\QueryBuilders\QueryBuilder;
+use Tempest\Database\Builder\QueryBuilders\WhereRawScope;
 use Tempest\Database\Exceptions\ModelDidNotHavePrimaryColumn;
 use Tempest\Database\QueryStatements\FieldStatement;
 use Tempest\Database\QueryStatements\JoinStatement;
 use Tempest\Database\QueryStatements\WhereExistsStatement;
 use Tempest\Reflection\PropertyReflector;
 use Tempest\Support\Arr\ImmutableArray;
+use UnitEnum;
 
 use function Tempest\Support\str;
 
@@ -191,4 +194,31 @@ private function getOwnerJoin(ModelInspector $ownerModel): string
             $this->getOwnerFieldName(),
         );
     }
+
+    public function query(PrimaryKey $primaryKey, null|string|UnitEnum $onDatabase = null): QueryBuilder
+    {
+        $relatedClassName = $this->property->getType()->getName();
+        $relatedModel = inspect(model: $this->property->getType()->asClass());
+        $ownerModel = inspect(model: $this->property->getClass());
+        $relatedTable = $relatedModel->getTableName();
+        $relatedPK = $relatedModel->getPrimaryKey();
+        $ownerTable = $ownerModel->getTableName();
+        $ownerPK = $ownerModel->getPrimaryKey();
+        $fk = $this->getOwnerFieldName();
+
+        return query(model: $relatedClassName)
+            ->onDatabase(databaseTag: $onDatabase)
+            ->scope(scope: new WhereRawScope(
+                statement: sprintf(
+                    '%s.%s = (SELECT %s FROM %s WHERE %s.%s = ?)',
+                    $relatedTable,
+                    $relatedPK,
+                    $fk,
+                    $ownerTable,
+                    $ownerTable,
+                    $ownerPK,
+                ),
+                binding: $primaryKey,
+            ));
+    }
 }

packages/database/src/BelongsToMany.php

@@ -6,12 +6,15 @@
 
 use Attribute;
 use Tempest\Database\Builder\ModelInspector;
+use Tempest\Database\Builder\QueryBuilders\QueryBuilder;
+use Tempest\Database\Builder\QueryBuilders\WhereRawScope;
 use Tempest\Database\Exceptions\ModelDidNotHavePrimaryColumn;
 use Tempest\Database\QueryStatements\FieldStatement;
 use Tempest\Database\QueryStatements\JoinStatement;
 use Tempest\Database\QueryStatements\WhereExistsStatement;
 use Tempest\Reflection\PropertyReflector;
 use Tempest\Support\Arr\ImmutableArray;
+use UnitEnum;
 
 use function Tempest\Support\arr;
 use function Tempest\Support\str;
@@ -394,4 +397,33 @@ public function getExistsStatement(): WhereExistsStatement
             ),
         );
     }
+
+    public function query(PrimaryKey $primaryKey, null|string|UnitEnum $onDatabase = null): QueryBuilder
+    {
+        $ownerModel = inspect(model: $this->property->getClass());
+        $targetModel = inspect(model: $this->property->getIterableType()->asClass());
+        $relatedClassName = $this->property->getIterableType()->getName();
+        $ownerTable = $ownerModel->getTableName();
+        $ownerPK = $ownerModel->getPrimaryKey();
+        $targetTable = $targetModel->getTableName();
+        $targetPK = $targetModel->getPrimaryKey();
+
+        $pivotTable = $this->resolvePivotTable(ownerModel: $ownerModel, targetModel: $targetModel);
+        $ownerFK = $this->ownerJoin ?? str(string: $ownerTable)->singularizeLastWord() . '_' . $ownerPK;
+        $targetFK = $this->relatedOwnerJoin ?? str(string: $targetTable)->singularizeLastWord() . '_' . $targetPK;
+
+        return query(model: $relatedClassName)
+            ->onDatabase(databaseTag: $onDatabase)
+            ->scope(scope: new WhereRawScope(
+                statement: sprintf(
+                    '%s.%s IN (SELECT %s FROM %s WHERE %s = ?)',
+                    $targetTable,
+                    $targetPK,
+                    $targetFK,
+                    $pivotTable,
+                    $ownerFK,
+                ),
+                binding: $primaryKey,
+            ));
+    }
 }

packages/database/src/Builder/QueryBuilders/HasWhereQueryBuilderMethods.php

@@ -15,6 +15,18 @@ trait HasWhereQueryBuilderMethods
     use HasConvenientWhereMethods;
     use HasWhereRelationMethods;
 
+    /**
+     * @param QueryScope[] $scopes
+     */
+    public function applyScopes(array $scopes): self
+    {
+        foreach ($scopes as $scope) {
+            $scope->apply(builder: $this);
+        }
+
+        return $this;
+    }
+
     protected function appendWhere(WhereStatement|WhereGroupStatement|WhereExistsStatement $where): void
     {
         $this->wheres->offsetSet(null, $where);

packages/database/src/Builder/QueryBuilders/QueryBuilder.php

@@ -19,11 +19,26 @@ final class QueryBuilder
 {
     use OnDatabase;
 
+    /** @var QueryScope[] */
+    private array $scopes = [];
+
     /** @param class-string<TModel>|TModel|string $model */
     public function __construct(
         private readonly string|object $model,
     ) {}
 
+    /**
+     * Adds a scope that will be applied to any query builder created from this instance.
+     *
+     * @return self<TModel>
+     */
+    public function scope(QueryScope $scope): self
+    {
+        $this->scopes[] = $scope;
+
+        return $this;
+    }
+
     /**
      * Creates a `SELECT` query builder for retrieving records from the database.
      *
@@ -41,7 +56,9 @@ public function select(string ...$columns): SelectQueryBuilder
         return new SelectQueryBuilder(
             model: $this->model,
             fields: $columns !== [] ? arr($columns)->unique() : null,
-        )->onDatabase($this->onDatabase);
+        )
+            ->onDatabase(databaseTag: $this->onDatabase)
+            ->applyScopes(scopes: $this->scopes);
     }
 
     /**
@@ -88,7 +105,9 @@ public function update(mixed ...$values): UpdateQueryBuilder
             model: $this->model,
             values: $values,
             serializerFactory: get(SerializerFactory::class),
-        )->onDatabase($this->onDatabase);
+        )
+            ->onDatabase(databaseTag: $this->onDatabase)
+            ->applyScopes(scopes: $this->scopes);
     }
 
     /**
@@ -106,7 +125,9 @@ public function update(mixed ...$values): UpdateQueryBuilder
      */
     public function delete(): DeleteQueryBuilder
     {
-        return new DeleteQueryBuilder($this->model)->onDatabase($this->onDatabase);
+        return new DeleteQueryBuilder(model: $this->model)
+            ->onDatabase(databaseTag: $this->onDatabase)
+            ->applyScopes(scopes: $this->scopes);
     }
 
     /**
@@ -124,7 +145,9 @@ public function count(?string $column = null): CountQueryBuilder
         return new CountQueryBuilder(
             model: $this->model,
             column: $column,
-        )->onDatabase($this->onDatabase);
+        )
+            ->onDatabase(databaseTag: $this->onDatabase)
+            ->applyScopes(scopes: $this->scopes);
     }
 
     /**

packages/database/src/Builder/QueryBuilders/QueryScope.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database\Builder\QueryBuilders;
+
+interface QueryScope
+{
+    public function apply(SupportsWhereStatements $builder): void;
+}

packages/database/src/Builder/QueryBuilders/SupportsWhereStatements.php

@@ -32,4 +32,11 @@ public function whereField(string $field, mixed $value, string|WhereOperator $op
      * @return self<TModel>
      */
     public function orWhere(string $field, mixed $value, WhereOperator $operator = WhereOperator::EQUALS): self;
+
+    /**
+     * Adds a raw WHERE condition to the query.
+     *
+     * @return self<TModel>
+     */
+    public function whereRaw(string $statement, mixed ...$bindings): self;
 }

packages/database/src/Builder/QueryBuilders/WhereFieldScope.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database\Builder\QueryBuilders;
+
+final readonly class WhereFieldScope implements QueryScope
+{
+    public function __construct(
+        private string $field,
+        private mixed $value,
+    ) {}
+
+    public function apply(SupportsWhereStatements $builder): void
+    {
+        $builder->whereField(field: $this->field, value: $this->value);
+    }
+}

packages/database/src/Builder/QueryBuilders/WhereRawScope.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database\Builder\QueryBuilders;
+
+final readonly class WhereRawScope implements QueryScope
+{
+    public function __construct(
+        private string $statement,
+        private mixed $binding,
+    ) {}
+
+    public function apply(SupportsWhereStatements $builder): void
+    {
+        $builder->whereRaw($this->statement, $this->binding);
+    }
+}

packages/database/src/Exceptions/PrimaryKeyWasNotInitialized.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database\Exceptions;
+
+use Exception;
+
+final class PrimaryKeyWasNotInitialized extends Exception
+{
+    public function __construct(
+        public readonly string $model,
+    ) {
+        parent::__construct("Cannot query relations on `{$model}` without a primary key value.");
+    }
+}

packages/database/src/Exceptions/PropertyWasNotARelation.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database\Exceptions;
+
+use Exception;
+
+final class PropertyWasNotARelation extends Exception
+{
+    public function __construct(
+        public readonly string $property,
+        public readonly string $model,
+    ) {
+        parent::__construct("Property `{$property}` is not a relation on `{$model}`.");
+    }
+}

packages/database/src/HasMany.php

@@ -6,12 +6,15 @@
 
 use Attribute;
 use Tempest\Database\Builder\ModelInspector;
+use Tempest\Database\Builder\QueryBuilders\QueryBuilder;
+use Tempest\Database\Builder\QueryBuilders\WhereFieldScope;
 use Tempest\Database\Exceptions\ModelDidNotHavePrimaryColumn;
 use Tempest\Database\QueryStatements\FieldStatement;
 use Tempest\Database\QueryStatements\JoinStatement;
 use Tempest\Database\QueryStatements\WhereExistsStatement;
 use Tempest\Reflection\PropertyReflector;
 use Tempest\Support\Arr\ImmutableArray;
+use UnitEnum;
 
 use function Tempest\Support\str;
 
@@ -178,6 +181,19 @@ public function getExistsStatement(): WhereExistsStatement
         );
     }
 
+    public function query(PrimaryKey $primaryKey, null|string|UnitEnum $onDatabase = null): QueryBuilder
+    {
+        $relatedClassName = $this->property->getIterableType()->getName();
+        $parentModel = inspect(model: $this->property->getClass());
+        $parentTable = $parentModel->getTableName();
+        $parentPK = $parentModel->getPrimaryKey();
+        $fk = $this->ownerJoin ?? str(string: $parentTable)->singularizeLastWord() . '_' . $parentPK;
+
+        return query(model: $relatedClassName)
+            ->onDatabase(databaseTag: $onDatabase)
+            ->scope(scope: new WhereFieldScope(field: $fk, value: $primaryKey));
+    }
+
     private function isSelfReferencing(): bool
     {
         $relationModel = inspect($this->property->getIterableType()->asClass());