Document a contract for accessing db-migrate as a module

[jpravetz]

This is not so much an issue as a request.
I'm including db-migrate as a module require() and writing my own equivalent of bin/db-migrate. This is because I need to manage and migrate a dynamically generated list of databases (e.g. one per customer).
The API is documents for use as a command line application, but not for use as a module, and I just want to make a request that an effort be made to stabilize this module API.
Thanks.

[kunklejr]

I agree this would be nice, but I'm hesitant to do it until the tool has had enough usage and I'm more confident the API wouldn't need to change.

[fatuhoku]

+1 for programmatic access. I'm thinking of using node-db-migrate to set up a file-based sqlite3 database for testing. Test data would be generated and inserted in, tests run, then the database would be discarded at the end of it all.

Changes to the API are pretty orthogonal to the way migrations are applied (i.e. invoking up and down), and so I am tempted.

For now the solution is to shell out.

[jpravetz]

We now most definitely do depend on a programmatic/module contract with db-migrate and never run db-migrate as a CL tool. We have a separate and more extensive CL tool over top of db-migrate that uses config files to define the db server, then migrates a named db on that server. We do this for several different database schemas. And we have a web app (admin.armor5.com) that uses db-migrate underneath and can dynamically add or delete a log database for a new customer. Hopefully, therefore, the existing module API sticks. Happily throughout all of this I've still been able to treat db-migrate's migration tools opaquely and not dig into it's mechanics to resolve bugs, etc.

[wzrdtales]

refers to #214