Configuration Reference

Emigrate can be configured using a configuration file, and it uses Cosmiconfig under the hood so you can use a variety of formats and locations for your configuration file.

Configure Emigrate

JavaScript

emigrate.config.js

/** @type {import('@emigrate/cli').EmigrateConfig} */
export default {
  directory: 'migrations',
};

TypeScript

emigrate.config.ts

import { type EmigrateConfig } from '@emigrate/cli';

const config: EmigrateConfig = {
  directory: 'migrations',
};

export default config;

You can specify the following options:

directory

type: string

Set the directory where your migrations are located, relative to the project root. This option is required by all Emigrate commands.

reporter

type: "pretty" | "json" | string | EmigrateReporter | Promise<EmigrateReporter> | (() => Promise<EmigrateReporter>)

default: "pretty" - the default reporter

Set the reporter to use for the different commands. Specifying a reporter is most useful in a CI or production environment where you either ship logs or want to have a machine-readable format.

emigrate.config.js

export default {
  reporter: 'json',
};

If you want to use different reporters for different commands, you can use an object:

emigrate.config.js

export default {
  up: {
    reporter: 'json',
  },
  new: {
    reporter: 'pretty', // Not really necessary, as it's the default
  },
};

Note

Commands that are not specified will use the default reporter.

Did you know?

The default reporter automatically detects if the current environment is an interactive terminal or not, and will only render animations and similar if it is.

color

type: boolean | undefined

default: undefined

Set whether to force colors in the output or not. This option is passed to the reporter which should respect it.

emigrate.config.js

export default {
  color: false,
};

storage

type: string | EmigrateStorage | Promise<EmigrateStorage> | (() => Promise<EmigrateStorage>)

Set the storage plugin to use for storing and reading the migration history. This option is required by all Emigrate commands except new which doesn’t use it.

emigrate.config.js

export default {
  storage: 'mysql',
};

Note

Each storage plugin can have its own configuration options, see the corresponding Storage Plugin section for more information.

plugins

type: Array<string | EmigratePlugin | Promise<EmigratePlugin> | (() => Promise<EmigratePlugin>)>

Set the plugins to use for the different commands. There are different types of plugins, and some are only useful for specific commands.

In short:

• Loader Plugins - are used for transforming non-JavaScript files into JavaScript files that can be executed by Node.js. These are only used by the up command.
• Generator Plugins - are used for generating new migration files. These are only used by the new command.

emigrate.config.js

export default {
  plugins: ['typescript'],
};

Did you know?

The same package can expose multiple plugins, so you can specify the plugin only once and it can be used as both a loader and a generator (and storage, in the case of MySQL for instance).

template

type: string

Set the path to a template file to use when creating new migrations. This option is only used by the new command.

emigrate.config.js

export default {
  new: {
    template: 'path/to/template.js',
  },
};

The migration file will use the template file’s extension, unless the extension option is set.

extension

type: string

Set the extension to use for new migrations. This option is only used by the new command.

emigrate.config.js

export default {
  new: {
    extension: '.ts',
  },
};

Will create new migration files with the .ts extension.

abortRespite

type: number
default: 10

Customize the number of seconds to wait before abandoning a running migration when the process is about to shutdown, for instance when the user presses Ctrl+C or when the container is being stopped (if running inside a container).

emigrate.config.js

export default {
  abortRespite: 10,
};