boco-migrate
Migrate all your things (not just databases)!
Table of Contents
Installation
Installation is available via npm or github.
$ npm install boco-migrate$ git clone https://github.com/bocodigitalmedia/boco-migrate
Usage
BocoMigrate = require "boco-migrate"lastMigration = null # Create a migrator migrator = storageAdapter: # Add migrations, in order migratoraddMigration id: "migration1" : lastMigration = @id; done : lastMigration = null; done migratoraddMigration id: "migration2" : lastMigration = @id; done : lastMigration = "migration1"; done migratoraddMigration id: "migration3" : lastMigration = @id; done : lastMigration = "migration2"; done
Migrating
passing null
or undefined
runs all pending migrations.
migratormigrate null throw error if error? expectlastMigrationtoEqual "migration3" ok
passing a target migrationId
migrates to the state of that migration.
migratormigrate "migration1" throw error if error? expectlastMigrationtoEqual "migration1" ok
Rolling Back
rollback
rolls back the latest migration.
migratormigrate null throw error if error? migratorrollback throw error if error? expectlastMigrationtoEqual "migration2" ok
Resetting
reset
rolls back all migrations.
migratormigrate null throw error if error? migratorreset throw error if error? expectlastMigrationtoEqual null ok
Storage Adapters
In order for the migrator to persist its state, you must provide it with an adapter for the storage mechanism of your choice.
The default StorageAdapter
is non-persistent, and thus is primarily used only for testing or as the parent class for other adapters.
testAdapter = null = migratorsetStorageAdapter adapter = adapterreset done = migratormigrate nulldone = migratorreset done series = resetAdaptertestMigratetestReset require"async"series seriesdone
File Storage Adapter
The BocoMigrate.FileStorageAdapter
writes data to the JSON file specified by the path
provided.
adapter = path: "migratorStorage.json" testAdapter adapter expecterror?toEqual false ok
Redis Storage Adapter
The BocoMigrate.RedisStorageAdapter
writes data to a redis
instance.
redisClient = require"redis"createClient adapter = redisClient: redisClient keyPrefix: "migrator" keyJoinString: "_" testAdapter adapter expecterror?toEqual false ok
Writing an Adapter
If you do not see an adapter you need, just subclass the StorageAdapter
class and modify it to suit the needs of your storage mechanism. If you end up writing an adapter, please create an issue for your adapter on this repository's github page.
Exceptions
Irreversible Migrations
A migration that has not defined a down
method will raise an IrreversibleMigration
error.
migratoraddMigration id: "migration4" : lastMigration = @id; done
A migration that has not defined a down
method will raise an IrreversibleMigration
error.
migratormigrate null throw error if error? migratorrollback expecterrorconstructortoEqual BocoMigrateIrreversibleMigration ok
Migration not Found
If you pass an id to migrate
that is not found, it will raise a MigrationNotFound
error.
migratormigrate "i dont exist" expecterrorconstructortoEqual BocoMigrateMigrationNotFound ok
Using the CLI
A CLI is provided with this package to allow you to run your migrations from the command line.
Usage: boco-migrate <options...> <command> [args...] options: -h, --help show this help screen -e, --example show an example migrator factory -f, --factory=factory_path path to the migrator factory defaults to "migratorFactory.js" commands: migrate [migration_id] Migrate to the (optional) target migration id rollback Roll back the latest migration reset Roll back all migrations info Show migration information set-latest-migration <migration_id> Set the latest migration id manually (does not run migrations). reset-latest-migration Reset the latest migration id. factory: A javascript file that exports a single async factory method, returning a migrator instance for the CLI.
Creating a Migrator Factory
Your migrator factory file must export a single async function, and returns a Migrator
instance. This allows you to connect to databases and perform other asynchronous tasks to initialize both the migrator as well as your migrations.
// file: "migratorFactory.js"var MyDBLib = ;var MyDBAdapter = ;var MyDBMigrations = ;var Migrator = Migrator; module { MyDBLib
Copyright (c) 2015 Christian Bradley + Boco Digital Media, LLC
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.