Installing this module adds a runnable file into your node_modules/.bin directory. If installed globally (with the -g option), you can run pg-migrate and if not, you can run ./node_modules/.bin/pg-migrate

When you run pg-migrate create a new migration file is created that looks like this:

exports.up=function(pgm, run){

run();

}

exports.down=function(pgm, run){

run();

}

pgm is a helper object that provides migration operations and run is the callback to call when you are done.

IMPORTANT
Generation of the up and down block is asynchronous, but each individal operation is not. Calling the migration functions on pgm doesn't actually migrate your database. These functions just add sql commands to a stack that is run after you call the callback.

If exports.down is not present in a migration, pg-migrate will try to automatically infer the operations that make up the down migration by reversing the operations of the up migration. Only some operations have automatically inferrable equivalents (details below on each operation). Sometimes, migrations are destructive and cannot be rolled back. In this case, you can set exports.down = false to tell pg-migrate that the down migration is impossible.

The pgm object that is passed to each up/down block has many different operations available. Each operation is simply a function that generates some sql and stores it in the current pgm context.

By default, each migration will be run in a transaction. To disable transactions for a specific migration, call pgm.noTransaction()
This is required for some SQL operations that cannot be run within a transaction. It should be used carefully.

The createTable and addColumns methods both take a columns argument that specifies column names and options. It is a object (key/value) where each key is the name of the column, and the value is another object that defines the options for the column.

type[string] - data type (use normal postgres types)

unique[boolean] - set to true to add a unique constraint on this column

primaryKey[boolean] - set to true to make this column the primary key

notNull[boolean] - set to true to make this column not null

check[string] - sql for a check constraint for this column

references[string] - a table name that this column is a foreign key to

Why only Postgres? - By writing this migration tool specifically for postgres instead of accommadating many databases, we can actually provide a full featured tool that is much simpler to use and maintain. I was tired of using crippled database tools just in case one day we switch our database.

Async / Sync - Everything is async in node, and that's great, but a migration tool should really just be a fancy wrapper that generates SQL. Most other migration tools force you to bring in control flow libraries or wrap everything in callbacks as soon as you want to do more than a single operation in a migration. Plus by building up a stack of operations, we can automatically infer down migrations (sometimes) to save even more time.

Naming / Raw Sql - Many tools force you to use their constants to do things like specify data types. Again, this tool should be a fancy wrapper that generates SQL, so whenever possible, it should just pass through user values directly to the SQL. The hard part is remembering the syntax of the specific operation, not remembering how to type "timestamp"!