Class Index | File Index

## Classes

- _Association
- _global_
- Dataset
- ManyToMany
- ManyToOne
- MayToOne
- Migrations
- Model
- moose
- moose.adapters
- moose.adapters.client.Client
- moose.adapters.client.ConnectionPool
- moose.adapters.client.mysql.ConnectionPool
- moose.adapters.client.mysql.Query
- moose.adapters.client.mysql.TransactionQuery
- moose.adapters.mysql
- moose.adapters.mysql.types
- moose.plugins
- moose.plugins.AssociationPlugin
- moose.plugins.CachePlugin
- moose.plugins.QueryPlugin
- moose.plugins.TimeStampPlugin
- moose.Table
- OneToMany
- SQL
- Type

# 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

- migrate - perform a migration
- createTable - to create a new table
- dropTable - drop a table
- alterTable - alter an existing table

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 <versionNumber>.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
--- | ---
| Migrations()

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)