Skip to main content

yarn db:migrate

yarn db:migrate performs three steps in sequence:

  1. saasframe generate – regenerates module registries, dependency injection bindings, entity ID maps, ORM entities, and API client.
  2. saasframe db migrate – runs MikroORM migrations for every enabled module in alphabetical order.
  3. saasframe entities install --global – ensures global custom entity and field definitions are synchronized.

You can also run migrations directly via the CLI:

# Using yarn script (includes generators + entity install)
yarn db:migrate

# Using CLI directly (migrations only)
yarn saasframe db migrate

Usage​

yarn db:migrate

The command relies on DATABASE_URL for database connectivity.

When to Run​

  • After pulling new migrations from version control.
  • After upgrading to a newer Open Saasframe version.
  • Immediately after yarn db:generate to apply fresh diffs.
  • During CI to guarantee the schema is aligned before running tests or seeding fixtures.
  • If you already have data and users, prefer yarn db:migrate over yarn initialize (which seeds data and may abort when users exist).

Output​

The script prints progress for each module with a progress bar showing migration application status (e.g., [====================] 3/3). Any failure aborts the remaining steps so you can resolve the issue safely.

Troubleshooting​

  • Migration errors — inspect the failing module's migration file in packages/<module>/src/modules/<module>/migrations. You can retry once the issue is resolved.
  • Custom entity sync errors — ensure Redis (if configured) is reachable so cache invalidation succeeds, or run yarn saasframe entities install --force afterwards.
  • Long-running migrations — consider running yarn db:migrate with NODE_ENV=production pointing to a managed database that has appropriate resources.