Skip to content
Sarj Code 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 outside migrations, add an exact SARJ105 suppression on the INSERT line explaining why. Migration SQL must declare an executable replay policy.

Examples

Before — flagged A replay guard for a different explicit schema is insufficient
queries/create_plan.sql
INSERT INTO
  live.plan
SELECT
  id
FROM
  pending
WHERE
  NOT EXISTS (
    SELECT
      1
    FROM
      archive.plan
    WHERE
      id = pending.id
  );
After — preferred A replay guard for the exact qualified target is retained
queries/create_plan.sql
INSERT INTO
  live.plan
SELECT
  id
FROM
  pending
WHERE
  NOT EXISTS (
    SELECT
      1
    FROM
      live.plan
    WHERE
      id = pending.id
  );
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