One Worker, One Brain Lane

"Serialize the scarce capability, not the whole application."

Bound the scarce lane

Parallelism is not automatically progress. Brain calls share routing, budgets, and attention with sibling systems. One serial worker makes the scarce lane explicit and keeps load predictable.

Release the database before the brain

The worker claims the oldest eligible queued row in a short transaction, marks it running, commits, then performs the slow call outside the lock. Completion returns through a second guarded transaction.

Do not turn serial into one giant lock

Holding a database transaction during a model call blocks unrelated work. Starting extra workers breaks the single-consumer contract and can duplicate calls. Serial does not mean one giant lock; it means one accountable consumer.

Operational invariant. Serialize the scarce capability, not the whole application.

Put crashes on the timeline

Test “One Worker, One Brain Lane” on a timeline where the process may disappear before acceptance, after commit, after claim, after the external call, or after output storage. At every cut, state what the database knows. A repeated request must not duplicate cost or prose.

Design it

Draw the worker loop and mark exactly where the database lock is released. Name statuses, timestamps, and attempt rows. Explain which evidence authorizes recovery instead of letting a cleanup script guess.

Observability is recoverability

An operator should distinguish queued, running, failed, and done with one query and know the next safe action. A silent unknown called a queue has already lost the work.

Code

Claim one eligible row quickly·sql

BEGIN IMMEDIATE;
SELECT id FROM jobs
WHERE status = 'queued'
ORDER BY created_at, id
LIMIT 1;
-- Bind the selected id as :job_id.
UPDATE jobs
SET status = 'running', started_at = CURRENT_TIMESTAMP
WHERE id = :job_id AND status = 'queued';
INSERT INTO job_attempts(
  job_id, attempt_number, status, started_at
)
SELECT :job_id, COALESCE(MAX(attempt_number), 0) + 1,
       'running', CURRENT_TIMESTAMP
FROM job_attempts WHERE job_id = :job_id;
COMMIT;
-- Perform the slow brain call only after COMMIT.

Bound the scarce lane

Release the database before the brain

Do not turn serial into one giant lock

Put crashes on the timeline

Design it

Observability is recoverability

Code

External links

Exercise

Progress

Comments 0