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',
  },
  remove: {
    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.
• Template Plugins - are used for generating the contents of 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 template plugin (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.

prefix

type: ”timestamp" | "timestamp-local" | "iso" | "iso-local" | "unix" | "unix-ms" | "numeric" | "none” | (name: string, lastMigration?: MigrationMetadata) => string
default: timestamp

The type of prefix to use for the new migration file.

emigrate.config.js

export default {
  new: {
    // A custom prefix function
    prefix: () => Math.random().toString(36).substring(2, 15),
    // Or a built-in prefix:
    prefix: 'timestamp-local',
  },
};

Will create new migration files with a prefix generated by the given prefix generator function or the specified built-in one.

Customizing the numeric prefix

If you want to customize the length of the built-in “numeric” prefix, you can import it and use it as a function:

emigrate.config.js

import { numeric } from '@emigrate/cli';

export default {
  new: {
    prefix: numeric(6), // 6 digits, e.g. 000001
  },
};

joiner

type: string
default: _

The string to use to join the prefix and the name of the migration file. It’s also used for replacing whitespace and characters that are not allowed in filenames in the name This option is only used by the new command.

emigrate.config.js

export default {
  new: {
    joiner: '-',
  },
};

Will create new migration files with the - as the word separator.

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,
};