agnostic-sql-migrator/README.md

Database agnostic migrator tool for SQL databases

# 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.

---

## Configuration

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`.

## Installation

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`

## Usage

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",
  migrationsPath,
  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.