feat(database): support uuids as primary columns (#1807)

Author: innocenzi

docs/1-essentials/03-database.md

@@ -124,7 +124,7 @@ Finally, you can make your own query builders if you want by implementing the {b
 
 ## Models
 
-A common use case in many applications is to represent persisted data as objects within your codebase. This is where model classes come in. Tempest tries to decouple models as best as possible from the database, so any object with public typed properties can represent a model.
+A common use case in many applications is to represent persisted data as objects within your codebase. This is where model classes come in. Tempest tries to decouple models as best as possible from the database, so any object with public typed properties can represent a table.
 
 These objects don't have to implement any interface—they may be plain-old PHP objects:
 
@@ -432,7 +432,7 @@ final class Book
 }
 ```
 
-Thanks to the {b`Tempest\Database\IsDatabaseModel`} trait, you can directly interact with the database via the model class:
+Thanks to the {b`Tempest\Database\IsDatabaseModel`} trait, you can interact with the database directly via the model class:
 
 ```php
 $book = Book::create(
@@ -455,6 +455,51 @@ $books = Book::select()
 $books[0]->chapters[2]->delete();
 ```
 
+### Using UUIDs as primary keys
+
+By default, Tempest uses auto-incrementing integers as primary keys. However, you can use UUIDs as primary keys instead by marking a {b`Tempest\Database\PrimaryKey`} property with the {b`#[Tempest\Database\Uuid]`} attribute. Tempest will automatically generate a UUID v7 value whenever a new model is created:
+
+```php src/Books/Book.php
+use Tempest\Database\PrimaryKey;
+use Tempest\Database\Uuid;
+
+final class Book
+{
+    #[Uuid]
+    public PrimaryKey $uuid;
+
+    public function __construct(
+        public string $title,
+        public string $author_name,
+    ) {}
+}
+```
+
+Within migrations, you may specify `uuid: true` to the `primary()` method, or directly use `uuid()`:
+
+```php src/Books/CreateBooksTable.php
+use Tempest\Database\MigratesUp;
+use Tempest\Database\QueryStatement;
+use Tempest\Database\QueryStatements\CreateTableStatement;
+
+final class CreateBooksTable implements MigratesUp
+{
+    public string $name = '2024-08-12_create_books_table';
+
+    public function up(): QueryStatement
+    {
+        return new CreateTableStatement('books')
+            ->primary('uuid', uuid: true)
+            ->text('title')
+            ->text('author_name');
+    }
+}
+```
+
+:::warning
+Currently, the `IsDatabaseModel` trait already provides a primary `$id` property. It is therefore not possible to use UUIDs alongside `IsDatabaseModel`.
+:::
+
 ## Migrations
 
 When you're persisting objects to the database, you'll need table to store its data in. A migration is a file instructing the framework how to manage that database schema. Tempest uses migrations to create and update databases across different environments.

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;
             }

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);
+    }
+}