README.markdown

Migrate - A database agnostic migration system for Node.js

By Ryan Sandor Richards

SQLite 3 Contribution by Curtis Schlak

Introduction

Migrate is a tool that allows you to define database schema migrations with
javascript. It borrows very heavily from the ruby migration system and contains
many of the same features. If you are unfamiliar with how migrations work don't
fret, just read on and everything will be explained!

Installation

Where, exactly, you include the migrate source in your project matters very
little as long as both migrate.js and config.js are in the same directory and
the node-mysql and migration paths in the configuration file are relative to
the directory where the migrate.js file resides.

The configuration file has the following keys:

dbms - The database management system to use (currently we only support a
a value of either 'mysql' or 'sqlite3').

migration_path - Relative path to the directory in which migrations are
stored.

mysql - Just a simple client configuration for mysql. Fill out your username,
password, and any other information needed to connect to the database via
node-mysql's Client class.

sqlite3 - Just a simple client configuration for SQLite 3. Fill out the
filename for the database to which you would like to connect.

How do I use migrate?

Once you have the configuration file filled you you can create a new migration
from the command line:

node migrate.js create create_users_table

This command will create a blank migration and stick it in the migrations folder
that you supplied in the configuration file. Once you fill out the migration's
up and down functions you can then apply the migration to your schema like so:

node migrate.js migrate

That command will determine if there are any migrations that have not been
applied and apply them sequentially until they are all done or one of them
fails.

If you wish to roll back any migrations that's super simple too, just use:

node migrate.js rollback

By default this will roll back only a single migration, but you can provide
a numeric parameter to tell it how many migrations you'd like it to roll back.
For instance, here's how you would roll back five migrations:

node migrate.js rollback 5

What is a migration?

A migration is a programmatic way of defining incremental database schema
changes. It has an "up" method for describing how to apply the changes, and a
"down" method for removing them. Here is an example migration:

In the above migration the "up" function creates a table named "users" with
three fields (id, email, and password) and a primary key on id. The "down"
function reverses these changes and simply drops the entire "users" table.

When you run the migration it gets converted into a collection of database
agnostic objects which are then translated into SQL for the appropriate DBMS.

What can I do in a migration?

The "up" and "down" methods of a migration support the exact same set of methods
. This means you can create and destroy schema information in both methods. The
Migration object supports the following methods:

create_table(name, body)

This method creates a table with the given name and passes the newly created table
representation to the supplied body closure.
From within the body closure one can execute methods on the table to add columns
and indices. Here is a complete list of all the "table" methods available:

t.column(name, type, options) - Creates a column with the given name, type
and additional options. Additional options include: limit, not_null,
precision, scale, and default_value. limit controls the number of
bytes to use for the integer type, not_null is used to determine if the
column is allowed to be null, precision and scale are used for the
decimal data type, and default_value allows you to set the default value
for the column.

t.primary_key(name) - Sets the primary key for the table to the column with
the given name.

t.index(name) - Sets an index on the table for the column with the given name

Finally the body also contains shortcut functions for each abstract data-type
tracked by Migrate. Each function has the form t.type(name, options) where name
and options are as explained in the t.column method. Here's a complete list:

Outtro

So that about sums it up. Simple and easy ;). It's a very early alpha version so
please don't hate on only having MySQL and SQLite 3 support! If you have a
feature request feel free to send me a message and I'll try to get it in ASAP.

Thanks!

License and Legalese

Copyright (c) 2010 Ryan Sandor Richards

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.