You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Migration guide at time of writing copied here for covenience:
Upgrading from v2.x
The Umzug class should be imported as a named import, i.e. import { Umzug } from 'umzug'.
The MigrationMeta type, which is returned by umzug.executed() and umzug.pending(), no longer has a file property - it has a name and optionalpath - since migrations are not necessarily bound to files on the file system.
The migrations.glob parameter replaces path, pattern and traverseDirectories. It can be used, in combination with cwd and ignore to do much more flexible file lookups. See https://npmjs.com/package/glob for more information on the syntax.
The migrations.resolve parameter replaces customResolver. Explicit support for wrap and nameFormatter has been removed - these can be easily implemented in a resolve function.
The constructor option logging is replaced by logger to allow for warn and error messages in future. NodeJS's global console object can be passed to this. To disable logging, replace logging: false with logger: undefined.
Events have moved from the default nodejs EventEmitter to emittery. It has better design for async code, a less bloated API surface and strong types. But, it doesn't allow passing multiple arguments to callbacks, so listeners have to change slightly, as well as .addListener(...) and .removeListener(...) no longer being supported (.on(...) and .off(...) should now be used):
The Umzug#execute method is removed. Use Umzug#up or Umzug#down.
The options for Umguz#up and Umzug#down have changed:
umzug.up({ to: 'some-name' }) and umzug.down({ to: 'some-name' }) are still valid.
umzug.up({ from: '...' }) and umzug.down({ from: '...' }) are no longer supported. To run migrations out-of-order (which is not generally recommended), you can explicitly use umzug.up({ migrations: ['...'] }) and umzug.down({ migrations: ['...'] }).
name matches must be exact. umzug.up({ to: 'some-n' }) will no longer match a migration called some-name.
umzug.down({ to: 0 }) is still valid but umzug.up({ to: 0 }) is not.
umzug.up({ migrations: ['m1', 'm2'] }) is still valid but the shorthand umzug.up(['m1', 'm2']) has been removed.
umzug.down({ migrations: ['m1', 'm2'] }) is still valid but the shorthand umzug.down(['m1', 'm2']) has been removed.
umzug.up({ migrations: ['m1', 'already-run'] }) will throw an error, if already-run is not found in the list of pending migrations.
umzug.down({ migrations: ['m1', 'has-not-been-run'] }) will throw an error, if has-not-been-run is not found in the list of executed migrations.
umzug.up({ migrations: ['m1', 'm2'], rerun: 'ALLOW' }) will re-apply migrations m1 and m2 even if they've already been run.
umzug.up({ migrations: ['m1', 'm2'], rerun: 'SKIP' }) will skip migrations m1 and m2 if they've already been run.
umzug.down({ migrations: ['m1', 'm2'], rerun: 'ALLOW' }) will "revert" migrations m1 and m2 even if they've never been run.
umzug.down({ migrations: ['m1', 'm2'], rerun: 'SKIP' }) will skip reverting migrations m1 and m2 if they haven't been run or are already reverted.
umzug.up({ migrations: ['m1', 'does-not-exist', 'm2'] }) will throw an error if the migration name is not found. Note that the error will be thrown and no migrations run unless all migration names are found - whether or not rerun: 'ALLOW' is added.
The context parameter replaces params, and is passed in as a property to migration functions as an options object, alongs side name and path. This means the signature for migrations, which in v2 was (context) => Promise<void>, has changed slightly in v3, to ({ name, path, context }) => Promise<void>.
Handling existing v2-format migrations
The resolve function can also be used to upgrade your umzug version to v3 when you have existing v2-compatible migrations:
const{ Umzug }=require('umzug');constumzug=newUmzug({migrations: {glob: 'migrations/umzug-v2-format/*.js',resolve: ({name, path, context})=>{// Adjust the migration from the new signature to the v2 signature, making easier to upgrade to v3constmigration=require(path)return{ name,up: async()=>migration.up(context),down: async()=>migration.down(context)}}},context: sequelize.getQueryInterface(),logger: console,});
Similarly, you no longer need migrationSorting, you can instantiate a new Umzug instance to manipulate migration lists directly:
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
Major release with some breaking changes since v2.x, see migration guide here: https://github.com/sequelize/umzug#upgrading-from-v2x
Several new features, including a new built-in CLI, typescript support, templating, improved events, logging and error messages, and more.
Find usage examples under https://github.com/sequelize/umzug/tree/master/examples
Migration guide at time of writing copied here for covenience:
Upgrading from v2.x
The Umzug class should be imported as a named import, i.e.
import { Umzug } from 'umzug'.The
MigrationMetatype, which is returned byumzug.executed()andumzug.pending(), no longer has afileproperty - it has anameand optionalpath- since migrations are not necessarily bound to files on the file system.The
migrations.globparameter replacespath,patternandtraverseDirectories. It can be used, in combination withcwdandignoreto do much more flexible file lookups. See https://npmjs.com/package/glob for more information on the syntax.The
migrations.resolveparameter replacescustomResolver. Explicit support forwrapandnameFormatterhas been removed - these can be easily implemented in aresolvefunction.The constructor option
loggingis replaced byloggerto allow forwarnanderrormessages in future. NodeJS's globalconsoleobject can be passed to this. To disable logging, replacelogging: falsewithlogger: undefined.Events have moved from the default nodejs
EventEmitterto emittery. It has better design for async code, a less bloated API surface and strong types. But, it doesn't allow passing multiple arguments to callbacks, so listeners have to change slightly, as well as.addListener(...)and.removeListener(...)no longer being supported (.on(...)and.off(...)should now be used):Before:
After:
The
Umzug#executemethod is removed. UseUmzug#uporUmzug#down.The options for
Umguz#upandUmzug#downhave changed:umzug.up({ to: 'some-name' })andumzug.down({ to: 'some-name' })are still valid.umzug.up({ from: '...' })andumzug.down({ from: '...' })are no longer supported. To run migrations out-of-order (which is not generally recommended), you can explicitly useumzug.up({ migrations: ['...'] })andumzug.down({ migrations: ['...'] }).umzug.up({ to: 'some-n' })will no longer match a migration calledsome-name.umzug.down({ to: 0 })is still valid butumzug.up({ to: 0 })is not.umzug.up({ migrations: ['m1', 'm2'] })is still valid but the shorthandumzug.up(['m1', 'm2'])has been removed.umzug.down({ migrations: ['m1', 'm2'] })is still valid but the shorthandumzug.down(['m1', 'm2'])has been removed.umzug.up({ migrations: ['m1', 'already-run'] })will throw an error, ifalready-runis not found in the list of pending migrations.umzug.down({ migrations: ['m1', 'has-not-been-run'] })will throw an error, ifhas-not-been-runis not found in the list of executed migrations.umzug.up({ migrations: ['m1', 'm2'], rerun: 'ALLOW' })will re-apply migrationsm1andm2even if they've already been run.umzug.up({ migrations: ['m1', 'm2'], rerun: 'SKIP' })will skip migrationsm1andm2if they've already been run.umzug.down({ migrations: ['m1', 'm2'], rerun: 'ALLOW' })will "revert" migrationsm1andm2even if they've never been run.umzug.down({ migrations: ['m1', 'm2'], rerun: 'SKIP' })will skip reverting migrationsm1andm2if they haven't been run or are already reverted.umzug.up({ migrations: ['m1', 'does-not-exist', 'm2'] })will throw an error if the migration name is not found. Note that the error will be thrown and no migrations run unless all migration names are found - whether or notrerun: 'ALLOW'is added.The
contextparameter replacesparams, and is passed in as a property to migration functions as an options object, alongs sidenameandpath. This means the signature for migrations, which in v2 was(context) => Promise<void>, has changed slightly in v3, to({ name, path, context }) => Promise<void>.Handling existing v2-format migrations
The
resolvefunction can also be used to upgrade your umzug version to v3 when you have existing v2-compatible migrations:Similarly, you no longer need
migrationSorting, you can instantiate a newUmzuginstance to manipulate migration lists directly:👇 full, generated changelog
What's Changed
stepin up and down options by @mmkal in Supportstepin up and down options #386unlogMigrationby @husa in fix #491. Fix MongoStorageunlogMigration#492.extend(...)in favour of constructor by @mmkal in Remove.extend(...)in favour of constructor #523New Contributors
unlogMigration#492Full Changelog: v2.3.0...v3.0.0
This discussion was created from the release v3.0.0.
Beta Was this translation helpful? Give feedback.
All reactions