The database package exports migration utilities and a schema builder from @veap/database/migrations. Feature packages such as auth and settings also include their own migration definitions.
Migration principles#
- Treat migrations as immutable, versioned history after deployment.
- Make schema changes explicit and review SQL implications before release.
- Separate schema changes from large data backfills when operationally appropriate.
- Test migrations from both an empty database and the previous released schema.
- Back up production data before destructive changes.
Application-owned migrations#
Use the migration runner and schema builder exported by the installed package. The exact function names and migration object shape are version-specific; inspect @veap/database/migrations declarations and the source examples for your installed release rather than copying Knex CLI conventions blindly.
Feature-provider migrations#
The authentication provider can run auth migrations during boot() when autoMigrate is enabled and the database is initialized. Its default is enabled. The settings package also supports migration setup through its provider configuration. For production, decide whether migrations run as a dedicated release step or during application startup; avoid multiple concurrent application instances racing to alter the same schema.
Production rollout#
Prefer backward-compatible migrations when deploying multiple application versions at once. A common sequence is: add nullable/new columns, deploy code that can read old and new shapes, backfill data, then enforce constraints in a later release. Destructive changes should follow a verified backup and rollback plan.
