TypeScript icon, indicating that this package has built-in type declarations

    1.0.4 • Public • Published

    Agnostic SQL Migrator

    A useful tool to carry out database migrations on Postgres, MySQL, or SQL Server databases. The tool was written in TypeScript and comes bundled with it's own types.


    This tool requires the SQL DB configuration information to be provided. This can be provided either via the environment, programmatically, or as command line arguments (if running locally).

    Argument precedence is as follows:

    A programmatic configuration variable takes highest precedence.

    This is then followed by a command line configuration variable.

    Then finally an environment variable.

    Possible command line arguments/environment variables are:

    • ADAPTER - the type of SQL database you are targeting accepting values postgres, sqlserver, or mysql (defined by the type Adapters)
    • USER - the user on the database to login as
    • PASSWORD - user password
    • HOST - host server location
    • PORT - host server port for connection
    • DATABASE - database name
    • MIGRATIONS_PATH - the directory that the migrations are located at

    There is also the optional VERSION argument which can be provided to specify which DB version to migrate to. If this remains unspecified then the migrator will migrate to the highest possible version of the database it can find.

    A restriction that is placed on the migration files is that they must be named as follows: [version from]-[version to].sql with the lowest possible version being 1. The versions can skip e.g. 1-4.sql. This also applies to rollback versions e.g. 4-1.sql.


    Install the tool via npm using:

    npm install agnostic-sql-migrator

    or if you're using yarn:

    yarn add agnostic-sql-migrator

    You will also need to install the relevant DB package:

    MySQL: npm install mysql2 or yarn add mysql2

    Postgres: npm install pg or yarn add pg

    SQL Server: npm install mssql or yarn add mssql


    Import and use the entrypoint using the following:

    If your configuration variables are already defined in your environment

    import {migrator} from 'agnostic-sql-migrator';
    const migrateDb = async () => {
        await migrator();

    Otherwise you can call:

    import {migrator, ClientConfig, MigrationConfig} fromm 'agnostic-sql-migrator';
    import {resolve} from 'path';
    const migrationsPath = resolve(PATH_TO_MIGRATIONS);
    const clientConfig: ClientConfig = {
      user: "postgres",
      password: "password",
      host: "localhost",
      port: 5432,
      database: "testdb"
    const migrationConfig: MigrationConfig = {
      adapter: "postgres",
      version: 10
    const migrate = async () => {
        await migrator({ClientConfig: clientConfig, MigrationConfig: migrationConfig});

    To call from command line you can use the following command:

    node_modules/.bin/agnostic-sql-migrator --VERSION=YOUR_VERSION for example.

    You can specify as many of the arguments described above as you like, but all the required arguments have to be specified either here in the command line, or as part of your environment variables, otherwise the command will fail.


    npm i agnostic-sql-migrator

    DownloadsWeekly Downloads






    Unpacked Size

    41.3 kB

    Total Files


    Last publish


    • aangelisc