abstract-migrator
Simple fixture for maintaining migrations that have their state stored in the storage that they reference.
Installation
$ yarn global add abstract-migrator
To make the amigrate
script available everywhere, or omit global
to install it in node_modules/.bin/
Supported data stores
These adapters should be short & simple, and they have access to the credentials on the stores they modify, so it's worth taking a look at their code to make sure everything is on the up-and-up:
- PostgreSQL
- Custom - see below
Configuration
In migrations/
, migrations/$type
or the parent folder of migrations
in your project, according to your preference, add conf.js
and (optionally) secrets.js
files that export enough information to connect to the relevant data store(s). (The split between conf and secrets is so you can commit common settings in the former and .gitignore
secrets.js for local credentials)
See the documentation for the module implementing migrations on your data store(s) to see which parameters are considered.
Usage
These examples assume you have cd
-ed to migrations/$type/
in your project path. You can also supply --path /project/path/migrations/$type
instead of relying on the working directory.
View help
$ amigrate
Usage: amigrate [options] verb [verb args]
... snip ...
Create a migration
$ amigrate create test migration
/project/path/migrations/$type/2018-05-24T17-00-55-821Z-test-migration.js
Since the output is the generated filename, you can edit immediately with, e.g.,
$ vim `amigrate create another test migration`
This is a file that exports { up, down }
methods that are passed an instance of a client connection to the data store. These methods should either do their work synchronously or return a Promise
that resolves when they're done.
You can change how these newly-created migrations look by creating & editing /project/path/migrations/$type/template.js
Run a migration
Single target:
$ amigrate up /project/path/migrations/$type/2018-05-24T17-00-55-821Z-test-migration.js
All unapplied:
$ amigrate up
Roll back a migration
Single target only:
$ amigrate down /project/path/migrations/$type/2018-05-24T17-00-55-821Z-test-migration.js
Custom adapters
There are examples above that serve as a good model. The formal requirements are:
index.js
should export a function that accepts configuration parameters and returns a Promise
that resolves to an instance of your adapter class when it's ready. The parameters are a hex-object
, which you can read about here, or just call .get()
on it to get a plain old object.
The adapter class must implement a few things:
get handle()
- A connection to the data store, passed toup()
anddown()
. The API here is up to you and the libraries you use, but callback-style APIs must be promisified.applied(name)
- Returns a boolean indicating whether a migration of the given name is already in the 'up' state.record(name)
- Mark the migration name as 'up'remove(name)
- Mark the migration name as 'down' (or just remove the 'up' mark)commit()
- Persist changes made this session permanently, where practicalrollback()
- Remove changes attempted this session, where practicalclose()
- Cleanly shut down the client connection