Class Index | File Index

Classes


Class Migrations

This is a plugin for moose to add migration functionality. Migrations are the preferred way of handling table creation, deletion, and altering.

Adds

Migrations are done through files contained in a particular directory, the directory should only contain migrations. In order for moose to determine which versions to use the file names must end in .js where versionNumber is a integer value representing the version num. An example directory structure might look like the following:
-migrations
     - createFirstTables.1.js
     - shortDescription.2.js
     - another.3.js
     .
     .
     .
     -lastMigration.n.js
In order to easily identify where certain schema alterations have taken place it is a good idea to provide a brief but meaningful migration name. createEmployee.1.js
In order to run a migraton all one has to do is call moose.migrate(options);
 moose.migrate({
              connection : {user : "test", password : "testpass", database : 'test'}, //Connection information to connect to the database.
              dir : "location of migrations", //Location of the directory containing the migrations.
              start : 0,//What version to start migrating at.
              end : 0,  //What version to stop migrations at.
              up : true //set to true to go up in migrations, false to rollback
 });

Example migration file


//Up function used to migrate up a version
exports.up = function() {
  //create a new table
  moose.createTable("company", function(table) {
      //the table instance is passed in.
      //add columns
      table.column("id", types.INT({allowNull : false, autoIncrement : true}));
      table.column("companyName", types.VARCHAR({length : 20, allowNull : false}));
      //set the primary key
      table.primaryKey("id");
  });
  moose.createTable("employee", function(table) {
      table.column("id", types.INT({allowNull : false, autoIncrement : true}));
      table.column("firstname", types.VARCHAR({length : 20, allowNull : false}));
      table.column("lastname", types.VARCHAR({length : 20, allowNull : false}));
      table.column("midinitial", types.CHAR({length : 1}));
      table.column("gender", types.ENUM({enums : ["M", "F"], allowNull : false}));
      table.column("street", types.VARCHAR({length : 50, allowNull : false}));
      table.column("city", types.VARCHAR({length : 20, allowNull : false}));
      table.primaryKey("id");
  });

  moose.createTable("companyEmployee", function(table) {
      table.column("companyId", types.INT({allowNull : false}));
      table.column("employeeId", types.INT({allowNull : false}));
      table.primaryKey(["companyId", "employeeId"]);
      table.foreignKey({companyId : {company : "id"}, employeeId : {employee : "id"}});
  });
  moose.createTable("works", function(table) {
      table.column("id", types.INT({allowNull : false, autoIncrement : true}));
      table.column("eid", types.INT({allowNull : false}));
      table.column("companyName", types.VARCHAR({length : 20, allowNull : false}));
      table.column("salary", types.DOUBLE({size : 8, digits : 2, allowNull : false}));
      table.primaryKey("id");
      table.foreignKey("eid", {employee : "id"});

  });
};

//Down function used to migrate down version
exports.down = function() {
   moose.dropTable("companyEmployee");
   moose.dropTable("works");
   moose.dropTable("employee");
   moose.dropTable("company");
};

Defined in: migrations.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Method Summary
Method Attributes Method Name and Description
 
alterTable(name, database, cb)
Alters a table
 
createTable(tableName, cb)

Creates a new table.

 
dropTable(table, database)
Drops a table
 
migrate(options)
Perform a migration.
Class Detail
Migrations()
Method Detail
{comb.Promise} alterTable(name, database, cb)
Alters a table
:

//alter table in default database
moose.alterTable("test", function(table){
    table.rename("test2");
    table.addColumn("myColumn", types.STRING());
});

//alter table in another database
moose.alterTable("test", "otherDB", function(table){
    table.rename("test2");
    table.addColumn("myColumn", types.STRING());
});
Parameters:
{String} name
The name of the table to alter.
{String} database Optional
the database that the table resides in, if a database is not provided then the default database is used.
{Function} cb
the function to execute with the table passed in as the first argument.
Returns:
{comb.Promise} There are two different results that the promise can be called back with.
  1. If a migration is currently being performed then the promise is called back with a function that should be called to actually perform the migration.
  2. If the called outside of a migration then the table is altered immediately and the promise is called back with the result.

{comb.Promise} createTable(tableName, cb)

Creates a new table. This function should be used while performing a migration.

If the table should be created in another DB then the table should have the database set on it.

//default database table creation
moose.createTable("test", function(table){
    table.column("id", types.INT())
    table.primaryKey("id");
});

//create a table in another database
moose.createTable("test", function(table){
    table.database = "otherDB";
    table.column("id", types.INT())
    table.primaryKey("id");
});
Parameters:
{String} tableName
the name of the table to create
{Funciton} cb
this funciton is callback with the table - All table properties should be specified within this block
Returns:
{comb.Promise} There are two different results that the promise can be called back with.
  1. If a migration is currently being performed then the promise is called back with a function that should be called to actually perform the migration.
  2. If the called outside of a migration then the table is created immediately and the promise is called back with the result.

{comb.Promise} dropTable(table, database)
Drops a table
//drop table in default database
moose.dropTable("test");

//drop table in another database.
moose.dropTable("test", "otherDB");
Parameters:
{String} table
the name of the table
{String} database Optional
the database that the table resides in, if a database is not provided then the default database is used.
Returns:
{comb.Promise} There are two different results that the promise can be called back with.
  1. If a migration is currently being performed then the promise is called back with a function that should be called to actually perform the migration.
  2. If the called outside of a migration then the table is dropped immediately and the promise is called back with the result.

{comb.Promise} migrate(options)
Perform a migration.
 moose.migrate({
              connection : {user : "test", password : "testpass", database : 'test'}, //Connection information to connect to the database.
              dir : "location of migrations", //Location of the directory containing the migrations.
              start : 0,//What version to start migrating at.
              end : 0,  //What version to stop migrations at.
              up : true //set to true to go up in migrations, false to rollback
 });

NOTE
If you start at 0 and end at 0 your migrations will inlude the file only at "migrationName".0.js if you specify start : 0 and end 1 then your migrations will include files "migraiton0".0.js and "migration1".1.js, the names being whatever you specify before the *.0 and *.1

Example migration file

//Up function used to migrate up a version
exports.up = function() {
  //create a new table
  moose.createTable("company", function(table) {
      //the table instance is passed in.
      //add columns
      table.column("id", types.INT({allowNull : false, autoIncrement : true}));
      table.column("companyName", types.VARCHAR({length : 20, allowNull : false}));
      //set the primary key
      table.primaryKey("id");
  });
  moose.createTable("employee", function(table) {
      table.column("id", types.INT({allowNull : false, autoIncrement : true}));
      table.column("firstname", types.VARCHAR({length : 20, allowNull : false}));
      table.column("lastname", types.VARCHAR({length : 20, allowNull : false}));
      table.column("midinitial", types.CHAR({length : 1}));
      table.column("gender", types.ENUM({enums : ["M", "F"], allowNull : false}));
      table.column("street", types.VARCHAR({length : 50, allowNull : false}));
      table.column("city", types.VARCHAR({length : 20, allowNull : false}));
      table.primaryKey("id");
  });

  moose.createTable("companyEmployee", function(table) {
      table.column("companyId", types.INT({allowNull : false}));
      table.column("employeeId", types.INT({allowNull : false}));
      table.primaryKey(["companyId", "employeeId"]);
      table.foreignKey({companyId : {company : "id"}, employeeId : {employee : "id"}});
  });
  moose.createTable("works", function(table) {
      table.column("id", types.INT({allowNull : false, autoIncrement : true}));
      table.column("eid", types.INT({allowNull : false}));
      table.column("companyName", types.VARCHAR({length : 20, allowNull : false}));
      table.column("salary", types.DOUBLE({size : 8, digits : 2, allowNull : false}));
      table.primaryKey("id");
      table.foreignKey("eid", {employee : "id"});

  });
};

//Down function used to migrate down version
exports.down = function() {
   moose.dropTable("companyEmployee");
   moose.dropTable("works");
   moose.dropTable("employee");
   moose.dropTable("company");
};
Parameters:
{Object} options
the options to specify how to perform the migration.
{Object} options.connection
: @see moose.createConnection
{String} options.dir
Location of the directory where migrations are located.
{Boolean} options.up Optional, Default: true
If true will migrate up otherwise down.
{Number} options.start Optional, Default: 0
The migration to start at.
{Number} options.end Optional, Default: Infinity
The migration to end at this, end is inclusive
Returns:
{comb.Promise} Called back after all migrations have completed.

Documentation generated by JsDoc Toolkit 2.4.0 on Sat Jun 11 2011 03:16:39 GMT-0500 (CDT)