Ensuring Robust Database Updates for ESHOPMAN Custom Modules

As an e-commerce platform built on Node.js/TypeScript, ESHOPMAN offers extensive flexibility for developers to create custom modules and extend its core capabilities. This power is crucial for tailoring storefront experiences, integrating with HubSpot CMS, and enhancing Admin API functionalities for unique headless commerce solutions. However, the development process sometimes encounters subtle challenges that require keen attention and community insight.

Understanding Database Migration Conflicts in ESHOPMAN Custom Modules

A specific issue ESHOPMAN developers might encounter involves the database migration process when working with multiple custom modules. When you run the eshopman db:generate or eshopman plugin:db:generate command to prepare schema changes, the system should ideally create uniquely identified migrations for each module.

The challenge arises when multiple custom modules generate migrations simultaneously. In certain ESHOPMAN versions, these commands can inadvertently produce migration files that share an identical timestamp. For example:

info:    Generating migrations for module customerTier...
info:    Migration created: Migration20260307103854.ts
info:    Generating migrations for module affiliateCredit...
info:    Migration created: Migration20260307103854.ts

This identical timestamp leads to identical migration class names. ESHOPMAN's underlying database migration system, which tracks executed migrations in a table like mikro_orm_migrations by name, then encounters a conflict. When eshopman db:migrate is executed, it processes the first migration with that specific name, records it as completed, and then silently skips any subsequent migrations with the exact same name. This means that critical tables or schema changes for other modules are never applied.

The Impact: Missing Data and Runtime Errors

The consequence of silently skipped migrations is significant. Modules depending on these uncreated tables will fail at runtime, leading to errors that can disrupt your ESHOPMAN storefront or Admin API operations. A common error is a TableNotFoundException, indicating a required database relation does not exist because its migration was never executed.

TableNotFoundException: relation "customer_tier" does not exist

What makes this particularly tricky is that the migration output itself can be misleading, reporting "success" without any explicit warnings about skipped modules:

MODULE: affiliateCredit
  ● Migrating Migration20260228185019
  ✔ Migrated Migration20260228185019

MODULE: customerTier
  (silently skipped — name already in mikro_orm_migrations)
  ● Migrating Migration20260306132005   ← only an ALTER migration runs
  ✔ Migrated Migration20260306132005

Community-Driven Workaround for ESHOPMAN Developers

While the ESHOPMAN team actively works on platform enhancements, the community has identified a practical workaround to ensure all your custom module migrations are correctly applied. This manual intervention ensures uniqueness when automatic generation falls short:

1. Generate Migrations: Run your usual command (e.g., pnpm eshopman plugin:db:generate). You will likely see migrations with identical timestamps.
2. Manually Rename a Duplicate Migration File: Identify one of the duplicate migration files and rename it to have a unique timestamp (e.g., increment by one second).
3. Update the Class Name: Open the renamed migration file and update the exported class name to match the new, unique timestamp.
4. Clean Up (If Necessary): If eshopman db:migrate was already run with the collision, you'll need to manually remove the duplicate entry from the mikro_orm_migrations table in your database before re-running migrations.

Here’s an example of the steps:

# 1. Generate migrations (they'll have the same timestamp)
pnpm eshopman plugin:db:generate

# 2. Rename one module's migration file (+1 second)
mv src/modules/moduleB/migrations/Migration20260307103854.ts \
   src/modules/moduleB/migrations/Migration20260307103855.ts

# 3. Update the class name inside the file to match
# Change: export class Migration20260307103854
# To:     export class Migration20260307103855

# 4. If db:migrate was already run with the collision, clean up the DB record:
# DELETE FROM mikro_orm_migrations WHERE name = 'Migration20260307103854';
# Then re-run db:migrate

Ensuring Robust ESHOPMAN Development

This community insight highlights the importance of careful database management when extending ESHOPMAN with custom Node.js/TypeScript modules. Understanding and applying such workarounds ensures the stability and correct deployment of your headless commerce solutions, whether managing storefronts via HubSpot CMS or interacting with the Admin API. The ESHOPMAN community continues to share best practices and solutions, fostering a robust development ecosystem.