Django Models

If a model has both kinds of FKs, that is fine and common. The presence of an HCFK is not a signal that the model should be in the other silo — it just means the relationship crosses silos.

Other norms worth encoding

Base class and timestamps

Use DefaultFieldsModel for new models. It gives you date_added (auto_now_add=True) and date_updated (auto_now=True) for free, and it's almost always what you want — tables that genuinely shouldn't track either timestamp are rare. DefaultFieldsModelExisting is legacy-only — its docstring explicitly says don't use it on new models (it leaves date_added nullable for backward compat with models that predate the field).

Field-type intent

• BoundedBigAutoField for primary keys, BoundedBigIntegerField / BoundedPositiveIntegerField for non-PK numeric IDs and counts. The "bounded" part is a runtime overflow guard, not a Django nicety — it catches values that would silently corrupt downstream consumers.
• For bounded text fields without a strict spec, prefer CharField(max_length=256). Postgres varchar(n) storage is identical regardless of n below the TOAST threshold, so picking 64 prematurely is a constraint without a benefit. Pick a smaller value only when the column has a real meaning (hash=40/64, UUID=32, slug, identifier with a spec).
• For free-form text fields, use TextField.
• For new JSON columns, prefer Django's models.JSONField() (jsonb-backed). The legacy sentry.db.models.fields.jsonfield.JSONField is text-backed and exists for compatibility with old columns — only use it when intentionally matching one.
• Mutable callable defaults (default=dict, default=list) — never bare default={} / default=[].

Soft delete is explicit

There is no metaclass-based soft delete. If a model needs soft delete, add an explicit status field using ObjectStatus and have business logic respect it. ParanoidModel exists (SentryAppInstallation uses it) but it is a heavyweight choice — most models should not need it.

Constraints over unique_together

For new models, use Meta.constraints = [UniqueConstraint(...)] instead of unique_together. The reason is condition=Q(...): partial unique constraints are the only correct way to express "unique when this column is not null", which is a common requirement and silently broken with unique_together. Constraint and index names should be explicit and descriptive, not auto-generated.

Composite indexes match query order

If you filter on (org_id, project_id, type) together, you need an index whose field order matches the most-selective-first filter pattern. A foreign key auto-index does not cover the multi-column case.

Where the file lives

• Default: put new models in an app under src/sentry/<app>/models.py (single file) or src/sentry/<app>/models/<thing>.py (one model per file) — pick by precedent in the app.
• src/sentry/models/<thing>.py is the legacy location. Only put a new model there if it's tightly coupled to a model that already lives there and moving it would be disruptive.
• New apps under src/sentry/<app>/ should set up a real Django app (apps.py, __init__.py with default_app_config).

A minimal cell-silo model skeleton

This is a starting scaffold, not a template — strip what you do not need, do not add things you do not need.

from __future__ import annotations

from django.db import models

from sentry.backup.scopes import RelocationScope
from sentry.db.models import DefaultFieldsModel, FlexibleForeignKey, cell_silo_model, sane_repr
from sentry.db.models.fields.hybrid_cloud_foreign_key import HybridCloudForeignKey


@cell_silo_model
class MyThing(DefaultFieldsModel):
    __relocation_scope__ = RelocationScope.Organization

    organization = FlexibleForeignKey("sentry.Organization")
    project = FlexibleForeignKey("sentry.Project")
    user_id = HybridCloudForeignKey("sentry.User", null=True,

    name = models.CharField(max_length=256)
    config = models.JSONField(default=dict)

    class Meta:
        app_label = "sentry"
        db_table = "sentry_mything"
        constraints = [
            models.UniqueConstraint(
                fields=["organization", "name"],
                name="sentry_mything_org_name_unique",
            ),
        ]

    __repr__ = sane_repr("organization_id", "project_id", "name")

For a control-silo model, swap @cell_silo_model for @control_silo_model. For a model whose state needs to be visible from the other silo, change the base to ReplicatedCellModel or ReplicatedControlModel and add category = OutboxCategory.MY_THING — then invoke the hybrid-cloud-outboxes skill for the rest.

After the model is designed

1. Generate the migration: invoke the generate-migration skill.
2. If the model is replicated: invoke the hybrid-cloud-outboxes skill to wire up payload, signal receivers, and deletion handlers.
3. If the app's models/__init__.py re-exports its models, add your new one there too — it's a convenience for callers (from sentry.<app>.models import Thing), not a Django requirement, so match the app's precedent.