Incidents

incidents is for running an outage and telling customers about it. You open an incident with a severity and the components it affects, post timeline updates as it moves from investigating to resolved, and write a postmortem afterwards. Each organization can publish one status page: the public components with their status and daily uptime, and the public incident updates. Visitors read it without signing in.

better-supabase add incidents

import { createIncidents } from "better-supabase/blocks/incidents";

The module requires tenant and access. With notifications the commander is notified when an incident opens, with outbox it records the events, and with audit every change is audited. The choices behind the anonymous surface are in ADR 0084.

TablesCopy Anchor Link

Members with incidents.read read every table. anon has no privileges on any of them.

ComponentsCopy Anchor Link

const incidents = createIncidents({ transport });

const api = await incidents
  .saveComponent(organizationId, { name: "API", group: "Platform" })
  .orThrow();
await incidents
  .saveComponent(organizationId, { name: "Primary database", public: false })
  .orThrow();

A component is public unless public is false. Its status is never set by hand: it is the worst impact of the open incidents on it (maintenance, degraded, partial_outage, major_outage), and operational when none is open. Every change is kept in the history the uptime is read from. Components and the status page need incidents.manage.

Run an incidentCopy Anchor Link

const incident = await incidents
  .open(organizationId, {
    title: "Elevated API errors",
    severity: "sev2",
    public: true,
    commanderId,
    message: "We are looking into elevated error rates.",
    impacts: [{ componentId: api.id, impact: "partial_outage" }],
  })
  .orThrow();

await incidents
  .postUpdate(incident.id, {
    status: "identified",
    body: "A replica fell behind; failing over.",
    public: false,
  })
  .orThrow();
await incidents
  .postUpdate(incident.id, { status: "resolved", body: "Resolved." })
  .orThrow();

An incident starts investigating with severity sev3 unless you pick one, and is private unless public is true. message becomes the first timeline update. Each postUpdate adds to the timeline and moves the incident to the update's status (investigating, identified, monitoring or resolved); resolving sets resolvedAt and returns its components to operational. An update is public when the incident is, unless it says otherwise. setImpacts replaces the affected components. Opening, updating, posting and writing the postmortem need incidents.write.

PostmortemsCopy Anchor Link

await incidents
  .savePostmortem(incident.id, {
    summary: "Replica lag caused failed writes.",
    rootCause: "A replica on an undersized disk",
    actionItems: [{ title: "Alert on replica lag", ownerId }],
  })
  .orThrow();
await incidents.publishPostmortem(incident.id).orThrow();

A postmortem can be drafted at any time and is published once the incident is resolved, with incidents.manage. The status page shows only its summary.

Status pageCopy Anchor Link

await incidents
  .saveStatusPage(organizationId, {
    slug: "acme",
    title: "Acme status",
    published: true,
  })
  .orThrow();

const page = await incidents.publicStatusPage("acme", 30).orThrow();

publicStatusPage(slug, days) works with the publishable key, signed in or not. It returns undefined unless the page is published. Otherwise it returns the page title and description, the overall status, each public component with its status, uptimePercent and one entry per day (1 to 90 days, default 90) with its worst status and minutes of outage, and the public incidents that are open or resolved in the window. Each incident carries its title, severity, status, start and end, the public components it affects, its public updates (newest first) and the summary of a published postmortem. Descriptions, commanders, private updates, private components, root causes, action items and ids of organizations and members never appear.

publicStatusPage is the only function anon may call. The pgTAP test in supabase/tests/database/incidents.test.sql checks that, and that a private incident never shows on the page.

ErrorsCopy Anchor Link

EventsCopy Anchor Link

incident.opened, incident.updated, incident.resolved, postmortem.published and status_component.changed. The events page lists their payloads.