Persistence on Brian Faust

A Version Column Is Not Concurrency Control

Sun, 01 Jan 2023 00:00:00 +0000

A capacity pool has ten units available. Two workers load it before either one writes:

worker A loads: version 0, reserved 0
worker B loads: version 0, reserved 0

worker A allocates 6 to allocation-a
worker B allocates 6 to allocation-b

Both decisions pass the aggregate’s rule. Each worker sees ten remaining units. They cannot both belong to one ordered history: after either allocation, only four remain.

Loading State Is Not Creating It Again

Thu, 01 Dec 2022 00:00:00 +0000

An order placed in 2024 is still in the database:

number=LEGACY-42
status=placed
fulfil_by=2024-12-20T10:00:00Z
version=7

Today, new web orders need a number beginning with WEB- and a fulfilment deadline in the future. Pass that stored row through today’s creation factory and one of two bad things happens. The factory rejects valid history, or the load pretends that placement happened again and records a new OrderPlaced fact.

A Mapper Connects Two Honest Models

Tue, 01 Nov 2022 00:00:00 +0000

An order in the domain has an OrderNumber, a Money total, typed lines, and an operation named place(). The same order in a relational database has an orders row, several order_lines rows, integer minor units, a nullable deadline, check constraints, a foreign key, and an index used by fulfilment.

Forcing those shapes to match exactly damages one side or the other.

Make the domain object mirror the tables and it acquires column names, nullable intermediate state, relationship-loading concerns, and methods shaped around persistence. Store the object as one opaque document and the database loses straightforward constraints and access paths required by the selected query.

A Repository Is a Domain Collection, Not an ORM Wrapper

Sat, 01 Oct 2022 00:00:00 +0000

This interface appears in many Laravel codebases:

interface Repository
{
 public function all(): Collection;
 public function find(int $id): ?Model;
 public function create(array $attributes): Model;
 public function update(int $id, array $attributes): Model;
 public function delete(int $id): bool;
}

It hides the word Eloquent and preserves everything else about Eloquent’s world: models, attribute arrays, record IDs, and CRUD operations. Callers still need to know which fields are writable, which relationships are loaded, and which operations preserve domain rules.

That is not a useful persistence boundary. It is a smaller, less capable ORM, which is an odd thing to spend an interface on.

A Composition Root Makes Choices Visible

Thu, 01 Sep 2022 00:00:00 +0000

Remove the ProductPrices binding from a Laravel service provider, then ask the container for QuoteProduct. Laravel refuses to construct it:

Target [App\Application\ProductPrices] is not instantiable while building
[App\Application\QuoteProduct].

Move the same lookup into QuoteProduct::execute() and construction succeeds. That can look like simplification because the constructor now says nothing. The object graph did not become simpler. Part of it moved into method code and configuration, where Laravel cannot reject it until a quote reaches that line.

A Hexagon Is Not a Directory Layout

Mon, 01 Aug 2022 00:00:00 +0000

A Laravel controller calls a catalogue API, reads price_cents, and returns a quote. Moving that HTTP code into Application/QuoteProduct.php makes the controller thinner. It also leaves the application service coupled to Laravel’s HTTP client, the provider URL, and the provider’s JSON.

The tree looks more architectural. The source dependencies have not moved. That is architecture by folder name, and it buys almost nothing.

That difference becomes visible when the catalogue replaces price_cents with price.amount_minor. A folder name cannot decide where the resulting change lands. A useful hexagonal boundary can: application policy defines the conversation it needs, while an outside adapter owns the provider mechanism.