fix(database): resolve uuid primary keys from positional insert bindings

[radoslav-grencik]

Fixes #2300

[github-actions]

Benchmark Results

Comparison of fix/uuid-pk-relation-inserts against 3.x (0f478fb487e12a5891738a15a1663fa44c47295b).

Open to see the benchmark results

Benchmark	Set	Mem. Peak	Time	Variability
ContainerBench(benchRegisterSingletonInstance)	-	6.107mb 0.00%	1.386μs -7.37%	±1.63% -43.14%
ContainerBench(benchRegisterClosureSingleton)	-	6.455mb 0.00%	1.457μs -5.65%	±3.07% +24.77%

_{Generated by phpbench against commit dbe65d6}

[radoslav-grencik]

What this PR does

Fixes relation auto-inserts for models with #[Uuid] primary keys, and adds the missing migration API needed to actually define UUID relationships.

1. Bug fix: Query::execute() resolved the wrong primary key after insert

Query::execute() looked up the primary key in $bindings[$primaryKeyColumn], but insert bindings are positional — the lookup never matched and execution always fell back to getLastInsertId(). For #[Uuid] primary keys that is the SQLite rowid / MySQL last_insert_id(), so BelongsToMany pivot rows and HasMany/HasOne child rows persisted a meaningless integer as the parent foreign key:

user_roles: user_id = "1"  -- rowid, not the user's UUID

The primary key is now resolved through its column position in the InsertStatement before falling back to getLastInsertId(). The auto-increment path is unchanged.

Covered by new integration tests (UuidPrimaryKeyTest):

• uuid_primary_key_belongs_to_many_pivot_uses_generated_uuid
• uuid_primary_key_has_many_uses_generated_uuid_as_foreign_key

2. Iterable insert() now generates #[Uuid] primary keys

Previously only the object path (create(), save()) generated UUID values; the iterable/array path silently omitted the primary key, which surfaced as Field 'id' doesn't have a default value on MySQL. resolveIterableData() now generates a UUID when the model has a #[Uuid] primary key and the key is absent from the given data. Explicitly provided ids are never overwritten.

This also makes UUID primary keys work for relation child rows inserted from arrays (e.g. chapters: [['title' => ...]]), which go through the iterable path internally.

Covered by uuid_primary_key_generated_for_iterable_insert.

3. Feature (bundled): UUID foreign key columns in migrations

While writing the tests it turned out there is no way to define a UUID-typed foreign key column: belongsTo() / foreignId() always compile INTEGER, and varchar(36) FK columns fail on PostgreSQL (character varying vs uuid type mismatch) — this PR's own CI caught it.

This PR therefore also adds:

• UuidStatement — a non-PK UUID column (CHAR(36) / UUID / TEXT per dialect)
• CreateTableStatement::uuidColumn(string $name, bool $nullable = false)
• CreateTableStatement::belongsToUuid(string $local, string $foreign, ...) — UUID counterpart of belongsTo()
• CreateTableStatement::foreignUuid(string $local, string $constrainedOn, ...) — UUID counterpart of foreignId()

The new integration test migrations use belongsToUuid() / foreignUuid(), so the UUID relation path is exercised end-to-end with real FK constraints on every dialect. Unit tests cover compilation for all three dialects (UuidStatementTest, CreateTableStatementTest::create_a_uuid_foreign_key_constraint).

Notes / known limitations (follow-ups, not part of this PR)

• Pivot tables need no primary key at all. Pivot rows are always addressed by their FK pair, never by their own id: inserts go through a table-name string (no model metadata), deletes and joins go through the FK columns. The pivot test table therefore declares no PK (matching the Laravel pivot convention). A composite PK was considered but deliberately not added — Tempest's ORM identity is single-column (PrimaryKey property, get($id), route binding), so a composite key would require a redesign far beyond this PR's scope.
• Batch insert + relations: execute() returns a single PrimaryKey and after callbacks run once, so relations are attached to the first row only. Pre-existing behavior for all PK types, unchanged by this PR.

[xHeaven]

What happens when an insert explicitly passes a 0 id?

[radoslav-grencik]

What happens when an insert explicitly passes a 0 id?

Good catch — that was a bug. When an insert explicitly passes id => 0, the positional resolution would return PrimaryKey(0) instead of falling back to getLastInsertId().

MySQL and PostgreSQL both treat INSERT ... VALUES (0, ...) on an auto-increment column as "use the sequence default", so the real id is 1 (or next sequence value). The fix was returning the explicit 0 — a non-existent row.

Fix: treat 0 the same as "no id provided" — fall back to getLastInsertId():

$value = $query->bindings[$index] ?? null;

// 0 is treated as "auto-increment" by MySQL/PostgreSQL — not a real id.
if ($value === 0 || $value === null) {
    return null;
}

return $value;

This is safe for UUID models too — a UUID entry never contains 0; the PK is always a generated UUID string.

Added a test (insert_with_zero_id_falls_back_to_last_insert_id) that inserts with explicit id => 0 and verifies the returned id is usable for retrieval.

[innocenzi]

This function name is inconsistent with our other names. We should probably repurpose uuid for this instead, and use primary as the sole way of creating primary UUIDs.

Would be breaking though, so for next major.