Skip to content
Sarj Sarj Sarj Standards

insert-requires-replay-policy

Every INSERT must declare replay-safe upsert behavior or explicitly document intentional insert-only semantics.

SARJ105 Rule source Tests Catalog JSON

Why

Retries happen in migrations, jobs, commands, and application requests. An INSERT with no declared conflict behavior can duplicate state or turn a safe retry into a uniqueness failure.

Fix

Prefer ON CONFLICT with an explicit DO NOTHING or DO UPDATE action. If duplicate failure is the intended contract, add an exact SARJ105 suppression on the INSERT line explaining why.

Examples

Before — flagged Insert without declared replay behavior
queries/create_plan.sql
INSERT INTO
  plan (name)
VALUES
  ('free');
After — preferred Upsert declares its conflict behavior
queries/create_plan.sql
INSERT INTO
  plan (name)
VALUES
  ('free')
ON CONFLICT (name) DO NOTHING;

Formerly: insert-requires-on-conflict