yarn install nomadic
A simple postgres migration tool built for both CLI and library usage.
$ yarn nomadic create hello-world; yarn nomadic; yarn nomadic down;import { up, down, create, migrate } from 'nomadic';
import { Nomadic } from 'nomadic/lib/nomadic';You can configure nomadic in 3 ways.
- Use nomadic.config.js (recommended)
- Import it to use as a library (advanced)
- Pass cli arguments
To see the arguments to pass run yarn nomadic help; nomadic will also merge cli arguments with nomadic.config.js values.
NOTE: nomadic.config.js values will
overwrite cli argument values.
Example nomadic.config.js:
module.exports = {
host: 'localhost', // url to your db server
database: 'nomadic',
migrations: 'migrations', // directory you want migrations placed in, relative to current working directory
migrationsTable: 'migrations', // Must be on the "public" schema. Defaults to 'migrations'
port: 5432,
user: 'postgres',
password: '',
preHooks: { // optional prehooks
up: async (client) => {
//...do something before all UP migrations are run here
},
down: async (client) => {
//...do something before all DOWN migrations are run here
},
create: async (client) => {
//...do something before running create here
}
},
hooks: { // optional hooks
// client is an instance of pg.Client
up: async (client) => {
//...do something after all UP migrations are run here
},
down: async (client) => {
//...do something after all DOWN migrations are run here
},
create: async (client) => {
//...do something after running create here
}
}
}$ yarn nomadic create <name-of-migration>This will create 3 files;
- A
<name-of-migration>.js file, which you can edit to run other Javascript on your up or down migrations. - A
<name-of-migration>-up.sql file with sql to make database schema changes - A
<name-of-migration>-down.sql file with sql to reverse the up database schema changes
Running yarn nomadic or yarn nomadic up will by default run all the up migrations that haven't been run.
You can also run e.g. yarn nomadic up 5 to migrate your db up 5 migrations.
To go down a migration:
yarn nomadic down will by default run 1 migration down at a time.
You can also run e.g. yarn nomadic down 5.
If you want to transform all sql code, you can pass a transform [(sql: string) => Promise<string>] option either in the nomadic.config.js or in the library options. It takes an sql string and returns whatever you want. It is passed as a function to all of your <name-of-migration>.js up and down functions. So you can rewrite sql / interpolate environment variables if needed.
Hooks (see above) allow you to run cleanup tasks after migration operations are done. For instance you may want to dump the schema, restart your dev server, etc.
Prehooks allow you to run tasks before migration operations are done.