Core ConceptsADR Library

ADR-008: MerchantConnectorExtension sidecar table

Status

Accepted (2026-05-28)

Context

Per-MCA metadata (operator labels, last health check, MVS-specific flags) needs to live somewhere. Two options: a JSON column on MerchantExtension or a sidecar table keyed by hyperswitch_merchant_connector_id.

Decision

Sidecar table MerchantConnectorExtension.

Consequences

  • Indexable per-MCA fields (e.g., filter by connectorName).
  • Clean cascading delete when an MCA is removed.
  • Slightly more schema surface than a JSON column.

Alternatives considered

  • JSON column on MerchantExtension: rejected — can’t index per-MCA queries efficiently, schema migrations harder.