Table of Contents
Ares allows you to release migration scripts to your MongoDB or Mysql instance.
Here is a step-by-step guide to installing this cli using NPM.
-
Use npm to install ares in your project folder
npm i ares-x
-
Change the config files or env variables to update your database connection info
-
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 --operation create --name test --dbms MYSQL -
Run with
ares --operation up
Here is a step-by-step guide to installing this cli using local clone.
-
Clone project using git
git clone [email protected]:Adibla/ares.git
-
Go to installation folder
cd ./ares -
Install dependencies
npm i
-
Change the config files or env variables to update your database connection info
-
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 loggingUNIX
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 loggingThis 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 --operation upWe 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.
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 achievedIt executes all migrations' up commands contained in MIGRATIONS_DIR
ares --operation upIt executes all migrations' down commands contained in MIGRATIONS_DIR, YOU CAN ONLY USE DOWN COMMAND FOR ALREADY DONE MIGRATIONS IN OUTCOME "COMPLETE_SUCCESS"
ares --operation downIt executes only migrations' with id specified (if exist) with up commands, contained in MIGRATIONS_DIR
ares --operation up --migration 001 002It 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 002It 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 --operation create --name test --author andrea --dbms MYSQL
ares --operation create --name test --author andrea --dbms MYSQL --description desc --tags tag1 tag2
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)
Unit tests can be run using Jest
npm run test- 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).
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!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE.txt for more information.
Andrea Di Blasi - @linkedin - [email protected]
Project Link: https://github.com/Adibla/ares