feat(database): support uuids as primary columns

Author: innocenzi

packages/database/src/Builder/ModelInspector.php

@@ -11,6 +11,7 @@
 use Tempest\Database\PrimaryKey;
 use Tempest\Database\Relation;
 use Tempest\Database\Table;
+use Tempest\Database\Uuid;
 use Tempest\Database\Virtual;
 use Tempest\Mapper\SerializeAs;
 use Tempest\Mapper\SerializeWith;
@@ -549,4 +550,14 @@ public function getPrimaryKeyValue(): ?PrimaryKey
 
         return $primaryKeyProperty->getValue($this->instance);
     }
+
+    public function hasUuidPrimaryKey(): bool
+    {
+        return $this->getPrimaryKeyProperty()?->hasAttribute(Uuid::class) ?? false;
+    }
+
+    public function isUuidPrimaryKey(PropertyReflector $property): bool
+    {
+        return $property->getType()->matches(PrimaryKey::class) && $property->hasAttribute(Uuid::class);
+    }
 }

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

@@ -21,6 +21,7 @@
 use Tempest\Reflection\PropertyReflector;
 use Tempest\Support\Arr;
 use Tempest\Support\Conditions\HasConditions;
+use Tempest\Support\Random;
 use Tempest\Support\Str\ImmutableString;
 
 use function Tempest\Database\inspect;
@@ -401,16 +402,22 @@ private function resolveObjectData(object $model): array
         $entry = [];
 
         foreach ($modelClass->getPublicProperties() as $property) {
+            $propertyName = $property->getName();
+
             if (! $property->isInitialized($model)) {
+                if ($definition->isUuidPrimaryKey($property)) {
+                    $uuid = new PrimaryKey(Random\uuid());
+                    $property->setValue($model, $uuid);
+                    $entry[$propertyName] = $this->serializeValue($property, $uuid);
+                }
+
                 continue;
             }
 
             if ($property->isVirtual()) {
                 continue;
             }
 
-            $propertyName = $property->getName();
-
             if ($property->hasAttribute(Virtual::class)) {
                 continue;
             }
@@ -435,10 +442,6 @@ private function resolveObjectData(object $model): array
 
             $column = $propertyName;
 
-            if ($property->getType()->getName() === PrimaryKey::class && $value === null) {
-                continue;
-            }
-
             if ($definition->isRelation($property)) {
                 [$column, $value] = $this->resolveRelationProperty($definition, $property, $value);
             } else {

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

@@ -264,7 +264,10 @@ public function create(mixed ...$params): object
 
         if ($id !== null && $primaryKeyProperty !== null) {
             $primaryKeyName = $primaryKeyProperty->getName();
-            $model->{$primaryKeyName} = new PrimaryKey($id);
+
+            if (! $inspector->hasUuidPrimaryKey() || $model->{$primaryKeyName} === null) {
+                $model->{$primaryKeyName} = new PrimaryKey($id);
+            }
         }
 
         return $model;

packages/database/src/IsDatabaseModel.php

@@ -248,7 +248,9 @@ public function save(): self
                 ->insert($this)
                 ->execute();
 
-            $primaryKeyProperty->setValue($this, $id);
+            if (! $model->hasUuidPrimaryKey()) {
+                $primaryKeyProperty->setValue($this, $id);
+            }
 
             return $this;
         }

packages/database/src/QueryStatements/CreateTableStatement.php

@@ -33,11 +33,28 @@ public static function forModel(string $modelClass): self
     }
 
     /**
-     * Adds a primary key column to the table. MySQL and SQLite use an auto-incrementing `INTEGER` column, and PostgreSQL uses `SERIAL`.
+     * Adds a primary key column to the table.
+     *
+     * By default, MySQL and SQLite use an auto-incrementing `INTEGER` column, and PostgreSQL uses `SERIAL`.
+     * When setting `uuid` to `true`, MySQL will use `VARCHAR(36)`, PostgreSQL will use `UUID`, and SQLite will use `TEXT`.
+     */
+    public function primary(string $name = 'id', bool $uuid = false): self
+    {
+        if ($uuid) {
+            $this->uuid($name);
+        } else {
+            $this->statements[] = new PrimaryKeyStatement($name);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Adds a UUID v7 primary key column to the table. Uses `VARCHAR(36)` for MySQL, `UUID` for PostgreSQL, and `TEXT` for SQLite.
      */
-    public function primary(string $name = 'id'): self
+    public function uuid(string $name = 'id'): self
     {
-        $this->statements[] = new PrimaryKeyStatement($name);
+        $this->statements[] = new UuidPrimaryKeyStatement($name);
 
         return $this;
     }

packages/database/src/QueryStatements/UuidPrimaryKeyStatement.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database\QueryStatements;
+
+use Tempest\Database\Config\DatabaseDialect;
+use Tempest\Database\QueryStatement;
+
+final readonly class UuidPrimaryKeyStatement implements QueryStatement
+{
+    public function __construct(
+        private string $name = 'id',
+    ) {}
+
+    public function compile(DatabaseDialect $dialect): string
+    {
+        return match ($dialect) {
+            DatabaseDialect::MYSQL => sprintf('`%s` VARCHAR(36) PRIMARY KEY', $this->name),
+            DatabaseDialect::POSTGRESQL => sprintf('`%s` UUID PRIMARY KEY', $this->name),
+            DatabaseDialect::SQLITE => sprintf('`%s` TEXT PRIMARY KEY', $this->name),
+        };
+    }
+}

packages/database/src/Uuid.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database;
+
+use Attribute;
+
+/**
+ * Marks a primary key property to automatically generate UUID v7 values when the model is saved.
+ * This must be applied to `PrimaryKey` properties that would use UUIDs instead of auto-incrementing integers.
+ *
+ * **Example**
+ * ```php
+ * final class User
+ * {
+ *     #[Uuid]
+ *     public PrimaryKey $uuid;
+ *
+ *     public function __construct(
+ *         public string $name,
+ *     ) {}
+ * }
+ * ```
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final readonly class Uuid
+{
+}

packages/database/tests/QueryStatements/CreateTableStatementTest.php

@@ -178,4 +178,59 @@ public static function provide_fk_create_table_database_drivers_explicit(): Gene
             SQL,
         ];
     }
+
+    #[DataProvider('provide_uuid_primary_database_dialects')]
+    public function test_create_table_with_uuid_primary(DatabaseDialect $dialect, string $validSql): void
+    {
+        $uuid = new CreateTableStatement('users')
+            ->uuid('uuid')
+            ->text('name')
+            ->text('email')
+            ->compile($dialect);
+
+        $primary = new CreateTableStatement('users')
+            ->primary('uuid', uuid: true)
+            ->text('name')
+            ->text('email')
+            ->compile($dialect);
+
+        $this->assertSame($validSql, $uuid);
+        $this->assertSame($validSql, $primary);
+    }
+
+    public static function provide_uuid_primary_database_dialects(): iterable
+    {
+        yield 'mysql' => [
+            DatabaseDialect::MYSQL,
+            <<<SQL
+            CREATE TABLE `users` (
+                `uuid` VARCHAR(36) PRIMARY KEY, 
+                `name` TEXT NOT NULL, 
+                `email` TEXT NOT NULL
+            );
+            SQL,
+        ];
+
+        yield 'postgresql' => [
+            DatabaseDialect::POSTGRESQL,
+            <<<SQL
+            CREATE TABLE `users` (
+                `uuid` UUID PRIMARY KEY, 
+                `name` TEXT NOT NULL, 
+                `email` TEXT NOT NULL
+            );
+            SQL,
+        ];
+
+        yield 'sqlite' => [
+            DatabaseDialect::SQLITE,
+            <<<SQL
+            CREATE TABLE `users` (
+                `uuid` TEXT PRIMARY KEY, 
+                `name` TEXT NOT NULL, 
+                `email` TEXT NOT NULL
+            );
+            SQL,
+        ];
+    }
 }

packages/database/tests/QueryStatements/UuidPrimaryKeyStatementTest.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database\Tests\QueryStatements;
+
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Tempest\Database\Config\DatabaseDialect;
+use Tempest\Database\QueryStatements\UuidPrimaryKeyStatement;
+
+/**
+ * @internal
+ */
+final class UuidPrimaryKeyStatementTest extends TestCase
+{
+    #[Test]
+    public function mysql_compilation(): void
+    {
+        $statement = new UuidPrimaryKeyStatement('uuid');
+        $compiled = $statement->compile(DatabaseDialect::MYSQL);
+
+        $this->assertSame('`uuid` VARCHAR(36) PRIMARY KEY', $compiled);
+    }
+
+    #[Test]
+    public function postgresql_compilation(): void
+    {
+        $statement = new UuidPrimaryKeyStatement('uuid');
+        $compiled = $statement->compile(DatabaseDialect::POSTGRESQL);
+
+        $this->assertSame('`uuid` UUID PRIMARY KEY', $compiled);
+    }
+
+    #[Test]
+    public function sqlite_compilation(): void
+    {
+        $statement = new UuidPrimaryKeyStatement('uuid');
+        $compiled = $statement->compile(DatabaseDialect::SQLITE);
+
+        $this->assertSame('`uuid` TEXT PRIMARY KEY', $compiled);
+    }
+
+    #[Test]
+    public function default_column_name(): void
+    {
+        $statement = new UuidPrimaryKeyStatement();
+        $compiled = $statement->compile(DatabaseDialect::MYSQL);
+
+        $this->assertSame('`id` VARCHAR(36) PRIMARY KEY', $compiled);
+    }
+}