Sentry Model Conventions

Sentry Model Conventions

This skill captures the architectural decisions that go into a Sentry model. It does not cover Django syntax, import order, or migration generation — for those:

• Migrations: invoke the generate-migration skill after the model is designed.
• Outbox replication plumbing (signal receivers, payload shapes, deletion handlers): invoke the hybrid-cloud-outboxes skill.
• Hybrid cloud RPCs: invoke the hybrid-cloud-rpc skill.

The four decisions that define a Sentry model

Before writing any fields, decide all four. They are coupled — getting one wrong forces a follow-up migration to fix the others.

1. Which silo does this data live in?

Cell silo (@cell_silo_model) is the default. Use control silo (@control_silo_model) only when the data is shared across organizations or has to be strongly consistent with other control-silo resources (auth, integration installs, API tokens, slug reservations).

The wrong way to think about it: "this is a user-facing thing, so control." The right way: "what is the smallest silo where this can correctly live, and is that silo the same as everything that mutates it together?" If a cell never reads it, it does not belong in the cell.

2. Does the other silo need to see this data?

If yes, the model must inherit from ReplicatedCellModel (cell-side) or ReplicatedControlModel (control-side) and set category: ClassVar[OutboxCategory] = OutboxCategory.MY_THING. The base Model class is for data that genuinely never crosses the silo boundary.

Replication is part of the design, not a thing you bolt on later. If you have to ask "should other silo X be able to look this up by ID without an RPC?" — that is a replication decision, and it changes the base class. When in doubt, defer to the hybrid-cloud-outboxes skill before finalizing the model.

3. Is this data part of an organization export (relocation)?

Every concrete model must set __relocation_scope__ — the runtime check at src/sentry/db/models/base.py raises if missing. The choice is almost always one of:

A set of scopes with a get_relocation_scope() override exists but is rare; reach for it only when relocation behavior is per-instance conditional. Excluded cannot be part of a set.

If you are not sure: most new models that store a customer's working state are Organization; most new models that exist for Sentry's operations (queues, caches, attempts, jobs, feature flags consumed at runtime) are Excluded.

4. What is the cross-silo blast radius of each foreign key?

The FK type is an architectural statement, not a style choice: