The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
Performance techniques from Medusa core, and how Mercur should apply them
Catalog of the optimization techniques used inside Medusa 2.x (read from the
develop branch at 2.21.0; the repo now pins 2.22.0). Every item names
where the technique lives in the Medusa source, what it does, and the rule Mercur
should follow. Paths are relative to the Medusa monorepo packages/ directory.
1. Workflows
1.1 Keep hot-path workflows non-stored
orchestration/src/transaction/distributed-transaction.ts:514,transaction-orchestrator.ts:1514-1523- A workflow writes a checkpoint to Redis/DB at every step boundary only if it
has
retentionTime,idempotent,timeout,retryInterval,store, or anasyncstep. Medusa's cart workflows have none of these, so they run fully in memory.completeCartWorkflowis the deliberate exception (store: true, retentionTime: 3 days), and gets idempotency from theorder_cartlink check plus a lock, not fromidempotent: true. - Mercur rule: never add those options to cart, offer, pricing, or listing
workflows. Get completion idempotency from a domain check (does the link
exist?). Do not pass deterministic
transactionIds on high-frequency routes (Medusa removed them in commit990691e78a).
1.2 parallelize() independent steps
- 94 call sites in
core/core-flows.complete-cart.ts:648runs link creation,completed_at, inventory reservation, promotion usage, and theorder.placedevent together.create-carts.ts:204runs sales channel, region and customer lookups together. - Mercur rule: seller lookup, commission rule resolution, and payout reads
that do not depend on each other go in one
parallelize.
1.3 when() guards and "skip if unchanged"
refresh-cart-items.ts:158,202,251: full repricing only onforce_refresh, whichupdate-cart.ts:390sets only when region, locale, or tax-relevant address changed. Otherwise only the touched line items get tax lines.refresh-payment-collection.ts:124: skips when amount and currency match.refresh-cart-shipping-methods.ts:64: skips when the cart has no methods.complete-cart.ts:409: the whole order branch iswhen(!orderId).- Mercur rule: gate commission recompute, split-order creation, and seller
notifications on what actually changed. Every step returns early on empty
input (30+ examples in
cart/steps).
1.4 Nested locks are skipped
locking/steps/acquire-lock.ts:69: inside a sub-workflow the step returnsStepResponse.skip()unlessexecuteOnSubWorkflowis set. Cart workflows usetimeout: 2, ttl: 10;completeCartusestimeout: 30, ttl: 120.- Mercur rule: use
acquireLockSteponcart_idin split-order completion with the same values. Lock inventory per inventory item (reserve-inventory.ts:88), never per seller or globally.
1.5 Pass loaded data into sub-workflows
- Refresh sub-workflows accept
cart?and fetch onlywhen(!input.cart). Purpose-built field constants live incart/utils/fields.ts(completeCartFields,cartFieldsForPricingContext, ...). get-variants-and-items-with-prices.tsindexes variants in aMap(commit5cc7fdef18) so per-item lookup is O(1).- Mercur rule: define per-purpose field constants, accept a preloaded entity
in sub-workflows, use
Maplookups intransform, and return several fields from onetransformsince results are memoized per transaction.
1.6 One bulk read, one bulk write
get-line-item-actions.ts:61: onelistLineItemswith anidarray, split into create/update sets.update-line-items.ts:55: one list (as the compensation snapshot) and oneupdateLineItems(items).get-variant-price-sets.ts:117: prices grouped by context, onecalculatePricesper distinct context, not per item.- Mercur rule: pass
{ id, ...data }[]to module update methods. Never selector-per-row.
1.7 Cheap compensation
getSelectsAndRelationsFromObjectArray(data)(51 files) snapshots only the columns being changed. Deletes are soft in the forward step and restored by ID in compensation. Read-only steps have no compensate function.- Payment is authorized last in
completeCart(complete-cart.ts:684) so the rollback window is small.
1.8 Chunking and async steps for long work
- Import: 1000 CSV rows per chunk (
normalize-products-to-chunks.ts:93), processed by anasync: truestep that frees memory between chunks. Export: batch size 50. Translations: 100. async: true, backgroundExecution: trueon export, import, and reindex workflows. The HTTP request returns at once.- Mercur rule: vendor CSV import/export, payout batches, and reindex use async background steps with 50 to 1000 item chunks. Never on cart paths.
1.9 Query cache inside workflows
useQueryGraphStepwithoptions.cache.enable: truefor reference data (region, shipping options, promotion codes, customer). Variant queries usecomputeAutomaticTags: trueplus explicit link-table tags incart/utils/fields.ts:212.- Mercur rule: Mercur link tables (seller-product, seller-order, offer
links) need explicit
Link<Name>:list:*tags or cached results go stale.
2. Query and data layer
2.1 How query.graph avoids N+1
core/query/src/joiner/remote-joiner.ts,execute.ts:386-516. The query is compiled into stages by depth and service; IDs are unioned and deduplicated so each relation level costs onelist({ [fk]: ids })per module. Sibling stages run in parallel. ID sets over 4000 are chunked with concurrency 10 (module-data-fetcher.ts:14).- Nested relations are fetched without a limit (
module-data-fetcher.ts:263). - A count query runs only when
skiporcursoris set;takealone does not. - Mercur rule: one
query.graphwith explicitfields, never a loop over sellers calling services. Each link hop adds one sequential stage. Do not expand unbounded one-to-many links (seller to products) in list views. Pass onlytakefor internal lookups to avoid the COUNT.
2.2 Cross-module filters stay in SQL only under conditions
core/query/src/joiner/cross-module-joins/index.ts,utils/src/dal/mikro-orm/cross-module-query/augment-find-options.ts. Filters and sorts on linked entities are rewritten intoEXISTSsubqueries if every hop is a link module or DML relation, all modules share the same database connection, and the field is a persisted, non-computed DML column. Otherwise the filter becomes "residual": the whole root set is loaded and filtered in memory, and pagination is re-applied afterwards (execute.ts:61-149).- Mercur rule: keep every Mercur module on the shared connection (no
database.clientUrl), usemodel.define, and filter only on persisted columns. This is the biggest cliff: filtering products by a seller field with pagination otherwise falls into memory.
2.3 MikroORM settings
mikro-orm-create-connection.ts:103:useBatchInserts,useBatchUpdates,batchSize: 100,implicitTransactions: false,autoJoinRefsForFilters: false, metadata cache on.- Default load strategy is
BALANCEDwith forced LEFT JOIN populates (mikro-orm-repository.ts:1535-1620). Override per call withconfig.options.strategy: "select-in"for wide one-to-many populates. - Each
@InjectManagercall forks the entity manager, so the identity map is per call. Transactions are reused only whensharedContextis threaded. upsertWithReplacedoes one SELECT, one bulk INSERT, then chunkednativeUpdateManyin parallel (mikro-orm-repository.ts:1294).- Product repository splits deep populates into one
populatecall per relation to dodge a MikroORM slow path (product/src/repositories/product.ts:76). - Inventory quantities are computed with raw knex sums
(
inventory/src/repositories/inventory-level.ts:13). - Mercur rule: thread
@MedusaContext() sharedContextthrough every nested service call. Use bulkcreate/updatearrays andupsertWithReplacefor vendor imports. Raw knex is acceptable for aggregates.
2.4 Indexes
- DML indexes are partial on
deleted_at IS NULLby default (dml/helpers/entity-builder/build-indexes.ts:17). EverybelongsToFK and everydeleted_atcolumn is indexed automatically. Link tables get FK anddeleted_atindexes (link-modules/src/utils/generate-entity.ts:104), butextraColumnsare not indexed. - Composite example
pricing/src/models/price-rule.ts:15:["price_id","attribute","operator"]unique and["attribute","value","price_id"]. GIN on jsonb:price-list-rule.ts:22(type: "gin"). - Mercur rule: declare composite indexes for every filter combination used
on list routes (
seller_id + status,seller_id + created_at, offerseller_id + sku). Any raw SQL must includedeleted_at IS NULLor the partial indexes are skipped. Add migrations for linkextraColumnsyou filter on.
2.5 Pricing
pricing/src/repositories/pricing.ts:66-315: candidate prices come from one knex query. Price-list rule matching uses a derived table withCOUNT(*) FILTER (...) = rules_countand jsonb@>; price rules use aLATERALsubquery. Denormalizedrules_countcolumns avoid counting at query time. Contexts with more than 10 keys are pruned against a cached distinct-attribute set.- Mercur rule: offer-scoped prices as
offer_idprice rules already use this single-query path. Pass the pricing context throughQueryContext(req.pricingContext)onvariants.calculated_price. Never callcalculatePricesper variant. Keep the context under 10 keys.
2.6 Index engine
modules/index: denormalizedindex_data(jsonb, GINjsonb_path_ops, partitioned per entity) andindex_relationtables. Synced by events in batches of 100 IDs, with full resync by keyset cursor under a lock. Listing runsSELECT DISTINCT root.idwith jsonb containment filters, then hydrates viaquery.graph. Count iscount_estimate()from EXPLAIN, only whenskipis set. Sync and listeners run only in worker/shared mode.- Mercur rule: mark the seller-product link
filterableso Seller is ingested and seller filtering stays inside the index. Accept estimated counts. Entity IDs must be ULIDs for keyset sync.
2.7 Pool, transactions, replicas
- One shared knex pool for all internal modules.
pool.mindefaults to 2,pool.maxhas no Medusa default (knex uses 10). Config viadatabaseDriverOptions.pool. Parallel joiner stages can use up to 10 connections per request. - No read replica support anywhere in core.
- Mercur rule: set
pool: { min: 2, max: 20 }per process and size(servers + workers) * maxwithin Postgres or PgBouncer limits.
2.8 Events
- Bulk service methods emit one message with
data.idas an array (event-builder-factory.ts:28). Workflows group events byeventGroupIdand release them only after commit (workflow-export.ts:636), staged in Redis with a 600 s TTL. Only events with subscribers are enqueued, via oneaddBulk. - Mercur rule: subscribers must handle
id: string[]. Emit from workflows withemitEventStepso events are dropped on rollback. Emit arrays in one call.
3. HTTP layer, caching, runtime
3.1 There is no HTTP response cache
Caching is at the data layer only: the cache option on query.graph and
query.index, active only when MEDUSA_FF_CACHING=true and the Caching Module
with a provider is registered. Medusa Cloud's published gains
(www/apps/cloud/app/cache/page.mdx):
| Endpoint | Before | After |
|---|---|---|
| GET /store/products | 354 ms | 83 ms |
| GET /store/products/:id | 161 ms | 123 ms |
| POST /store/carts/:id/line-items | 697 ms | 427 ms |
| POST /store/carts/:id/complete | 1357 ms | 1018 ms |
| GET /store/shipping-options | 272 ms | 173 ms |
- Keys hash fields, filters, pagination, pricing context, and locale, so
entries split per region and customer group. Invalidation is tag-based and
driven by a
*event subscriber that parses<entity>.<op>events intoEntity:idandEntity:list:*tags. In-flight identical gets are coalesced. Redis provider gzips payloads over 2 KB and uses pipelines. useCache(cb, { key, tags, ttl })and the@Cacheddecorator wrap any computation, and are no-ops when caching is off.- Mercur rule: pass
{ cache: { enable: true }, locale }on seller and product listing routes, as the core store products route does. Emit Mercur module events asseller.updated,commission_rate.updatedwith{ id }so Seller entries invalidate. Always selectidin cached queries. Wrap commission rule resolution and seller shipping aggregation inuseCache. Never mutate cached results in place (memory provider usesuseClones: false). Use a separateCACHE_REDIS_URLso cache evictions do not touch queues. Core gaps to fix in Mercur copies:setTaxContextrefetches the region without cache, and customer groups insetPricingContextare not cached.
3.2 Worker mode and clustering
workerMode:shared(default),server,worker. Inworkermode there is no Express app. Subscribers load everywhere so servers know which events to enqueue, but only workers process them. Scheduled jobs, workflow engine retries, index sync, and the cleaner run only in worker/shared.medusa start --cluster N --servers X --workers Yforks processes and re-forks crashed ones.- Mercur rule: production runs N
WORKER_MODE=serverreplicas plus one or moreworker. Mercur subscribers and payout jobs then run off the request path automatically. Never do heavy work inonApplicationStartwithout checkingworker_mode !== "server".
3.3 Query config and limits
- Store routes get
storeRelationsLimit3 (default) or per-route override; the products route uses 4.fieldsnested deeper than 2 levels are rejected. Default list limit is 50, and there is no maximumlimitin core. - Mercur rule:
/vendor/*routes never getreq.storeRelationsLimit, so add a vendor middleware that sets it. Add.max(100)to Mercur find-paramslimit. UseallowFields(...)instead of widening core allowlists. Requestinventory_quantityonly when needed. Vendor product lists must use curated fields, never the*-relation defaults.
3.4 Express settings
- Gzip is off by default (
http.compression.enabled, threshold 1 KB). Enable only without a CDN or nginx in front. - Body parsers are memoized per config; routes can set
bodyParser: false(multer uploads) orpreserveRawBody: true(Stripe Connect webhooks only). - Sessions use Redis when
redisUrlis set; without it every node has its own in-memory store and horizontal scaling breaks. Sessionresave: trueby default; setfalseto cut Redis writes. Bearer JWT for the vendor panel skips session lookups entirely.
3.5 Redis modules
- Event bus:
removeOnComplete: true,attempts: 1, workerconcurrency: 1on Cloud. SetworkerOptions.concurrency: 5-10on workers if Mercur subscribers are I/O-bound and idempotent. Passattemptsandbackoffper emit for notification events. - Locking: default lease 60 s, auto-renewed every lease/3, wait timeout 5 s,
retry 20 ms with exponential backoff and jitter. Register
locking-redisas the default provider in multi-instance deployments. - Workflow engine: three queues (main, jobs, cleaner) with separate
workerOptions.concurrency. The Redis storage writes to Postgres only at handover points (commitbd206cb250) and uses pipelines withNXfor "already started" detection. KeepretentionTimeshort or unset soworkflow_executionstays small.
3.6 Store product listing path (reference for seller-scoped listing)
Middleware chain in medusa/src/api/store/products/middlewares.ts:
authenticate (optional) → validate query (limit 50, depth 4) → sales channel
filter from publishable key → applyMaybeLinkFilterIfNecessary (skips the link
pre-query when the index engine is on, or when only one sales channel exists)
→ default filters → normalizeDataForContext (region from cart or cached store
default) → setPricingContext (cached region, uncached customer groups) →
setTaxContext → clear context keys. Handler uses query.index when the flag
is on and no tag/category/option filters are present, otherwise query.graph,
both with cache: { enable: true }. Tax prices are wrapped in one batched
getTaxLines call after the query.
Mercur rule: reuse normalizeDataForContext, setPricingContext, and
setTaxContext from @medusajs/medusa/api/utils/middlewares. Copy the
"skip the filter when only one exists" trick for seller filters.
4. Applied on perf/core-hot-path-optimizations
- Checkout: lock timeout/ttl and
retentionTimewere passed in milliseconds (an 8 hour lock wait, 33 hour lock, 8 year retention); now seconds like core. The cart lock is also taken when checkout runs nested underprocessPaymentWorkflow, which releases its own lock first. Shipping options, promotion sellers, seller-customer links and offer inventory are read in oneparallelize; link creation and offer-link mirroring join the post-order fan-out. - Commission:
getCommissionLinesBatchon the module service and system provider loads the rate table once per checkout instead of once per seller order. The order fetch is trimmed to the fields the context builder reads. Providers may implement the optional batch method; the module falls back to per-context calls otherwise. - Split payments: lock taken on the nested path, two reads parallelized.
- Steps: early returns on empty input for offer create/update and every
link-seller-*step; offer updates pass{ id, ...data }so the module does one lookup instead of one per selector. - Vendor product scoping: single-product visibility and ownership checks are
filtered by
product_idinstead of loading the wholeproduct_sellertable and every product the seller ever created. - Cache opt-in on reference reads: visible sellers, sales-channel stock locations, seller regions and currencies, store product list and detail (with locale).
- Order-group list SQL: soft-deleted orders, links and summaries excluded from the aggregates and filters.
- Indexes:
order_group(cart_id, customer_id+created_at, created_at),offer(seller_id+created_at, product_id+seller_id+created_at),payout(account_id+created_at, status+created_at),review(reference+status+created_at),commission_rule(reference+reference_id).commission_linedeclares the indexes its migration already created.
5. Priority checklist for Mercur before load testing
- Audit every Mercur workflow for
retentionTime,idempotent,timeout,retryInterval, andasyncon hot paths. Remove them. - Audit every
query.graphcall for missingfields,*-relation defaults, and expanded unbounded links. - Find filters on computed or cross-connection fields that fall into residual in-memory filtering, especially product-by-seller listing with pagination.
- Add composite partial indexes for the seller-scoped list filters on orders, offers, product changes, and payouts.
- Thread
sharedContextthrough every nested service call in Mercur modules. - Mark the seller-product link
filterableand move store listing toquery.index. - Enable the caching flag plus Redis provider, add link-table tags to Mercur
cached queries, and emit
<entity>.<op>events from Mercur modules. - Cap
limit, set the relations limit on/vendor/*, and setdatabaseDriverOptions.pool.max. - Run server/worker split with
locking-redisregistered. - Move payout batches, imports, and exports to async background steps.
Useful Medusa commits to read with git show in the Medusa checkout:
2fe68a975b, c54c5ed6de, 990691e78a, d1efad9bf0, 5cc7fdef18,
bd206cb250, 8e5c22a8e8, bd571aca82.