0.1.0 • Published 1 year ago

ares-x v0.1.0

Weekly downloads
-
License
MIT
Repository
-
Last release
1 year ago

MIT License LinkedIn

About The Project

Ares allows you to release migration scripts to your MongoDB or Mysql instance.

Getting Started

Installation with npm

Here is a step-by-step guide to installing this cli using NPM.

  1. Use npm to install ares in your project folder
    npm i ares

  2. Change the config files or env variables to update your database connection info

  3. Using Ares or manually, create one or more migrations and place them in the MIGRATIONS_DIR folder (default data-ares on your project root).

    ares-x --operation create --name test --dbms MYSQL
  4. Run with
    ares-x --operation up

Installation with local clone

Here is a step-by-step guide to installing this cli using local clone.

  1. Clone project using git
    git clone git@github.com:Adibla/ares.git
  2. Go to installation folder
    cd ./ares
  3. Install dependencies
    npm i

  4. Change the config files or env variables to update your database connection info

  5. Run with

    npm run start -- --operation up

##Usage Specify your database configuration via ENV variables (or use USE_CUSTOM_CONFIG=true and update PROJECT/config/{env}.json)

WINDOWS

 set DB_HOST="localhost"
 set DB_PORT=27017
 set DB_USER="test"
 set DB_PASS="test"
 set DB_NAME="test"
 set AUTH_MECHANISM="test"
 set AUTH_SOURCE="test"
 set SERVICE_NAME="test" //for logging

UNIX

 export DB_HOST="localhost"
 export DB_PORT=27017
 export DB_USER="test"
 export DB_PASS="test"
 export DB_NAME="test"
 export AUTH_MECHANISM="test"
 export AUTH_SOURCE="test"
 export SERVICE_NAME="test" //for logging

This pattern must be followed if you use config files

{
  "db": {
    "connection": {
      "host": "localhost",
      "port": 27017,
      "user": "admin",
      "password": "secret",
      "database": "test",
      "authMechanism": "DEFAULT",
      "authSource": "admin"
    },
    "migrationsStoreTable":{
      "tableName": "migrations-store",
      "tableId": "id"
    },
    "seeds": {
      "directory": "./priv/seeds"
    }
  },
  "app":{
    "migrationsDir": "./ares-data",
    "operationsLabels": {
      "statusExecuted": "EXECUTED",
      "statusRolledBack": "ROLLED_BACK",
      "statusPending": "PENDING",
      "rolledBackSuccess": "ROLLED_BACK_SUCCESS",
      "rolledBackFailed": "ROLLED_BACK_FAILED",
      "outcomeSuccess": "COMPLETE_SUCCESS",
      "outcomeFailed": "COMPLETE_FAILED",
      "outcomeMissing": "NONE"
    }
  },
  "log": {
    "name": "app",
    "base": {
      "env": "dev"
    },
    "enabled": true,
    "level": 20
  }
}

After running the app, Ares creates a new table in your database with generated migrations (included in your MIGRATIONS_DIR), whose name is specified by MIGRATIONS_STORE env (migrations-store by default).

IMPORTANT CURRENTLY THE FIRST MIGRATION DICTATES WHICH DBMS WILL BE USED (for multiple dbms supports, see Roadmap

ares-x --operation up

We will execute all migrations' up commands in the MIGRATIONS_DIR folder and save their status in the database. There are currently some migration examples in the folder.

ENVIRONMENT VARIABLES

In order to configure the application, you can use several environment variables (someone has default values).

  DB_HOST="localhost" #required
  DB_PORT=27017 #required
  DB_USER="admin" #required
  DB_PASS="secret" #required
  DB_NAME="test" #required
  USE_CUSTOM_CONFIG=false #It is used to include custom config files (instead of using env) located in ProjectDir/config/[env].json.
  AUTH_MECHANISM="DEFAULT"
  AUTH_SOURCE="admin"
  SERVICE_NAME="test"
  MIGRATIONS_STORE="migrations-store" #Migration support table used by Ares for migrations
  MIGRATIONS_STORE_ID="test" #The primary key of the migration table used by Ares for migrations
  MIGRATIONS_DIR="./ares-data" #Folder that includes migrations file
  STATUS_EXECUTED="COMPLETE_SUCCESS" #Status of migration if it is successful
  STATUS_ROLLED_BACK="STATUS_ROLLED_BACK" #Status of migration if it is rolledback
  STATUS_PENDING="STATUS_PENDING" #Status of migration if it is pending
  ROLLED_BACK_SUCCESS="ROLLED_BACK_SUCCESS" #Result of migration if it is rolled back with success
  ROLLED_BACK_FAILED="ROLLED_BACK_FAILED" #Result of migration if it is rolled back with errors
  OUTCOME_SUCCESS="OUTCOME_SUCCESS" #Result of migration if it is successful
  OUTCOME_FAILED="OUTCOME_FAILED"  #Result of migration if it is failed
  OUTCOME_MISSING="OUTCOME_MISSING" #Status of migration if no outcome is achieved

COMMAND LINE OPTIONS

It executes all migrations' up commands contained in MIGRATIONS_DIR

   ares-x --operation up

It executes all migrations' down commands contained in MIGRATIONS_DIR, YOU CAN ONLY USE DOWN COMMAND FOR ALREADY DONE MIGRATIONS IN OUTCOME "COMPLETE_SUCCESS"

   ares-x --operation down

It executes only migrations' with id specified (if exist) with up commands, contained in MIGRATIONS_DIR

   ares-x --operation up --migration 001 002

It executes only migrations' with id specified (if exist) with down commands, contained in MIGRATIONS_DIR, YOU CAN ONLY USE DOWN COMMAND FOR ALREADY DONE MIGRATIONS IN OUTCOME "COMPLETE_SUCCESS"

   ares --operation down --migration 001 002

It creates new migration schema in MIGRATION_DIR, you have to specify --name (migration's name) param and --dbms (mysql or mongodb) and you could optionally includes other not required params (author, description, tags)

   ares-x --operation create --name test --author andrea --dbms MYSQL
   ares-x --operation create --name test --author andrea --dbms MYSQL --description desc --tags tag1 tag2

MIGRATION ENTITY SPECIFICATION

A migration filename may include title, id, and author, separated by "-", for example, "001-example-andrea.json", but the same attributes may also be included in the migration body. Currently, json is the only filetype supported. Migration entity contains these attributes, they will be persisted in Ares' config table.

  • id (string) - Migration's id, it could be specified in filename or body
  • author (string) - Migration's Author, it could be specified in body or filename.
  • dbms (string 'MYSQL'|'MONGODB') - Migration's dbms, it could be specified only in body.
  • tag(string) - Migration's tag, it could be specified only in body.
  • description(string) - Migration's description, it could be specified only in body.
  • comment(string) - Migration's comment, it could be specified only in body.
  • title(string) - Migration's title, it could be specified in filename or in body.
  • labels(string) - Migration's labels, it could be specified only in body.
  • up(string|RunCommandOptions) - Migration's up, it could be specified only in body, in case of MongoDB it's a RunCommandOptions.
  • down(string|RunCommandOptions) - Migration's down, it could be specified only in body, in case of MongoDB it's a RunCommandOptions.
  • ares_version(string) - Ares version, taken directly from package.json
  • status(string) - Migration's status
  • outcome(string) - Migration's outcome
  • filename(string) - Migration's filename
  • checksum(string) - Migration's checksum (automatically generated)
  • created_at(date) - Migration's creation timestamp (automatically generated)

TEST

Unit tests can be run using Jest

npm run test

Roadmap

  • First draft
  • Add Changelog
  • Add back to top links
  • Custom messages for some use cases (already existing migration exc...)
  • Improve errors management
  • Manage multiple dbms in single transaction (think about that)
  • Connect to MongoDB once, no need to create multiple instances
  • Remove "any" everywhere and use types for everything
  • Other dbms support
  • Validation checksum
  • YAML support
  • Improve README and Documentation
  • Support new Dbms
  • Move all labels to config file
  • Better input validation
  • More unit test
  • Generate package with npm
  • Manage errors in flow
  • WIP

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Andrea Di Blasi - @linkedin - andrea.diblasix@gmail.com

Project Link: https://github.com/Adibla/ares

@babel/preset-typescript@types/config@types/handlebars-helpers@types/jest@types/ramda@types/yargsajvchalkconfigfiglethandlebarsinquirerknexmongodbmysqlmysql2objectionpinoramdashelljssqlite3ts-nodetypescriptyargs
@infinitebrahmanuniverse/nolb-are@everything-registry/sub-chunk-1162
0.1.0

1 year ago