setup method is undocumented

[ab-pm]

I've just started using db-migrate, and the create command generates a module file containing the following lines:

var dbm;
var type;
var seed;

/**
  * We receive the dbmigrate dependency from dbmigrate initially.
  * This enables us to not have to rely on NODE_PATH.
  */
exports.setup = function(options, seedLink) {
  dbm = options.dbmigrate;
  type = dbm.dataType;
  seed = seedLink;
};

I have no idea what the setup method is supposed to do here (seems like its creates a few module-scoped variables, and dbm is probably getting passed require('db-migrate') but without having to declare an explicit dependency), and what I need this for. The pattern seems really bulky as well. Couldn't one just declare the up and down functions inside the setup, so that everything is in scope?

Unfortunately, the documentation doesn't seem to mention this anywhere, there is no guide on how to write a migration file successfully.

[wzrdtales]

This is to retain backwards compatibility. Since we couldn't put anything else in the parameters as they're frozen and have a callback so they can't change this setup method was introduced. It fixed old baggage from a very early state of db-migrate (before I overtook the library). In this stage these parameters were defined globally by db-migrate, which is a big issue for when we come to the point of today where db-migrate can be directly integrated into your application.

However, there are new migration schemas in work and may be I will give version 1 a lift up and also a new version where the setup method disappears, but that is yet open for conception.

Please have a look here #627 to understand what currently happens and is in development. Actually there is a functional beta version in npm with the new schema already, however some thing are yet only partially implemented. The new migration schema is a completely new tier in itself, but just have a look in the linked issue.

However the setup method is purely optional.

node-db-migrate/lib/migrator.js

Lines 233 to 235 in 263db65

	if (typeof setup === 'function') {
	setup(self.internals.migrationOptions, self.seedLink);
	}

If it does not exist, it will not be called. So if you have no need for the defined datatypes or other things passed in that function, you can safely delete it.