Skip to main content

Polyglot Data Stores

Two primary databases, each doing what it is best at, plus Redis and object storage. The golden rule:

Money, orders, inventory, ledgers → PostgreSQL. Documents, history, content → MongoDB. Each fact has exactly one owner.

Ownership map​

StoreOwnerHolds
PostgreSQLMedusaproducts, variants, options, kits, categories, pricing/price-lists, carts/orders, promotions, inventory + reservations, sales channels, payments, fulfillment, customers, customer groups, tax
PostgreSQLFinance (NestJS, see note)dealer ledgers, GST documents, payouts, reconciliation — relational financial truth
MongoDBFSMservice tickets, jobs/visits, AMC contracts, SLA timers, technician profiles
MongoDBWarrantyassets (serial lifecycle), registrations, warranty claims, external assets
MongoDBDMSchannel partners, tiers, KYC, targets, schemes, beat plans
MongoDBLoyaltypoints ledgers (non-financial), tiers, affiliate links/attribution
MongoDBCRMcustomer 360 projections, segments
MongoDBPayloadposts, pages, testimonials, FAQ, media metadata
MongoDBTenant Configbranding + feature flags + behavior
Redissharedcache, sessions, BullMQ queues + delayed jobs
Object Storagesharedmedia, branding assets, generated PDFs

Note on financial data in NestJS: even though the dealer-ledger workflow lives in a NestJS domain, the ledger itself is stored in Postgres for ACID + auditability. NestJS domains may therefore use both Mongo (operational/document data) and a Postgres schema (financial records). Mongo is the default; Postgres is used wherever money correctness matters.

What crosses the boundary (and how)​

Domain services frequently need commerce facts (which order, which product, which customer). They get them by reference + denormalized snapshot, never by querying Medusa's tables directly.

  • Each domain document stores the Medusa IDs it relates to (medusaOrderId, medusaProductId, medusaCustomerId).
  • It also stores a snapshot of the fields it needs to display/reason about, so it is not coupled to live Medusa reads.
  • If fuller commerce data is needed on demand, the BFF composes it by calling Medusa's API — but transactional logic in a domain never depends on a synchronous Medusa call.

Consistency model​

  • Source of truth for a fact is its owner store only.
  • Cross-store updates are eventually consistent via events (see Eventing).
  • Consumers are idempotent (dedupe on event id) and use an outbox on the producing side so an event is never lost if a write commits.

Anti-patterns (do not do)​

  • ❌ A NestJS service writing into Medusa's Postgres tables.
  • ❌ Storing money/inventory truth in Mongo "for convenience."
  • ❌ Two stores both claiming to own the same fact.
  • ❌ Synchronous cross-store joins inside a transaction.

Backups & migration​

  • Postgres and Mongo each have independent backup schedules per tenant.
  • Migrations: Medusa migrations (Postgres) run via Medusa CLI; Mongo schema evolution is handled by versioned migration scripts in each NestJS service.