{"id":22900545,"url":"https://github.com/rioastamal/shgrate","last_synced_at":"2025-05-08T01:24:12.736Z","repository":{"id":145535319,"uuid":"55355006","full_name":"rioastamal/shgrate","owner":"rioastamal","description":"shgrate is a simple database schema migration for MySQL written in Bash.","archived":false,"fork":false,"pushed_at":"2016-04-10T10:59:32.000Z","size":24,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"development","last_synced_at":"2025-03-31T16:11:26.639Z","etag":null,"topics":["bash","database","mysql","schema-migrations"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rioastamal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-04-03T15:59:16.000Z","updated_at":"2018-12-15T00:48:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"ec29e87d-cb7a-49b6-83e5-04747ca43e08","html_url":"https://github.com/rioastamal/shgrate","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rioastamal%2Fshgrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rioastamal%2Fshgrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rioastamal%2Fshgrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rioastamal%2Fshgrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rioastamal","download_url":"https://codeload.github.com/rioastamal/shgrate/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252979794,"owners_count":21835115,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","database","mysql","schema-migrations"],"created_at":"2024-12-14T01:28:46.220Z","updated_at":"2025-05-08T01:24:12.711Z","avatar_url":"https://github.com/rioastamal.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Overview\n\nshgrate is a simple database schema migration script for MySQL written in Bash.\nIt can be used as general purpose schema migration utility for a project. Let\nsay you're building an application using a framework but this framework does\nnot provide you the schema migration - then you can use shgrate to 'version\ncontrol' your database.\n\nMost of the migration tools save the migrated actions into the database itself.\nshgrate takes difference approach where all the migrated script is saved in\na directory so all the migrated script can be easily viewed without having\nto connect to the database.\n\nshgrate needs three directories in order to do its job. \n\nDirectory | Use for\n----------|--------\nmigrations | Used to store the SQL migration scripts\nmigrated | Used to store actions which has been migrated\nrollback | Used to store the SQL rollback scripts\n\nKeep it mind that these directories are configurable via environment variable or config file. But by default shgrate expect these directories are on the same directory as shgrate.\n\n## Requirements\n\nshgrate require Bash (tested with Bash 4.3.11), MySQL client binary and other shell core utilities:\n\n* awk\n* date\n* diff\n* grep\n* sort\n* tr\n\nThose shell utilities should be available in most Linux distribution and Unix\ncompatible OS such as Mac OS X - even Windows using cygwin.\n\n## Installation\n\nClone the project repository via github:\n\n```\n$ git clone git@github.com/astasoft/shgrate\n```\n\nAnother altertive is download the zip tarball and extract it somewhere on your box.\n\n## Basic Usage and Examples\n\nRunning shgrate with `-h` option will give you list of option that shgrate supports.\n\n```\nUsage: ./shgrate.sh [OPTIONS]\n\nWhere OPTIONS:\n  -a NAME       use database NAME\n  -b            rollback mode\n  -c FILE       read the config file from the FILE\n  -e ENVIRON    specify environment name by ENVIRON. Default is 'production'\n  -h            print this help and exit\n  -m NAME       create a migration file named NAME\n  -o FILE       save the log to the FILE\n  -r            dry run\n  -v            print the shgrate version\n\nshgrate is a simple database schema migration for MySQL written in Bash.\nshgrate is free software licensed under MIT. Visit the project homepage\nat http://github.com/astasoft/shgrate.\n```\n\nCommon steps when using shgrate as migration tools should covered by list below.\n\n1. Prepare the database used for the migration\n2. Create the directories for shgrate\n3. Create the migration file\n4. Run the migration\n5. Rollback the changes\n\nLet's walkthrough the steps above.\n\n### 1. Prepare the database for the migration\n\nLogin to the MySQL server.\n\n```\nmysql\u003e CREATE DATABASE mytestdb;\n```\n\n### 2. Create the directories for shgrate\n\nOn this example we will create these directories on the same directory as shgrate.\n\n```\n$ mkdir migrations migrated rollback\n```\n\n### 3. Create the migration file\n\nWhen you create a migration file, shgrate automatically create the corresponded rollback file. You should edit and put your SQL statement on both files.\n\n```\n$ ./shgrate.sh -m create_table_user\nMigration file: migrations/2016_04_05_21_06_20_create_table_user.sg_migrate.sql.\nRollback file: rollback/2016_04_05_21_06_20_create_table_user.sg_migrate.sql.\n```\n\nBelow is a sample of the content of migration and rollback file we just created. You can edit the files using your favorite text editor. On the example below I put simple statement to create table called \"user\".\n\n```\n$ cat migrations/2016_04_05_21_06_20_create_table_user.sg_migrate.sql\n-- shgrate Migration Script\n-- Generated by: shgrate v1.0\n-- File: 2016_04_05_21_06_20_create_table_user.sg_migrate.sql\n-- Date: Tue, 05 Apr 2016 21:06:20 +0800\n-- Write your SQL migration below this line\nCREATE TABLE user (\n    id INT NOT NULL AUTO_INCREMENT,\n    user_email VARCHAR(100) NOT NULL,\n    PRIMARY KEY (id)\n) Engine=InnoDB;\n\n$ cat rollback/2016_04_05_21_06_20_create_table_user.sg_migrate.sql\n-- shgrate Rollback Script\n-- Generated by: shgrate v1.0\n-- File: 2016_04_05_21_06_20_create_table_user.sg_migrate.sql\n-- Date: Tue, 05 Apr 2016 21:06:20 +0800\n-- Write your SQL rolllback migration below this line\nDROP TABLE user;\n```\n\n### 4. Run the migration\n\nBefore running the migration it's good practice to see what shgrate would execute by running in dry run mode using `-r` option. Option `-a` tells shgrate the name of database to use.\n\n```\n$ ./shgrate -a mytestdb -r\nMigrating 2016_04_05_21_06_20_create_table_user.sg_migrate.sql...done.\n\u003e\u003e Contents of file migrations/2016_04_05_21_06_20_create_table_user.sg_migrate.sql: \n-- shgrate Migration Script\n-- Generated by: shgrate v1.0\n-- File: 2016_04_05_21_06_20_create_table_user.sg_migrate.sql\n-- Date: Tue, 05 Apr 2016 21:06:20 +0800\n-- Write your SQL migration below this line\nCREATE TABLE user (\n    id INT NOT NULL AUTO_INCREMENT,\n    user_email VARCHAR(100) NOT NULL,\n    PRIMARY KEY (id)\n) Engine=InnoDB;\n```\n\nAfter you're sure that all the statement is correct, you can proceed the real migration.\n\n```\n$ ./shgrate -a mytestdb\nMigrating 2016_04_05_21_06_20_create_table_user.sg_migrate.sql...done.\n```\n\nCheck the database to see table \"user\" has been successfully created or not.\n\n### 5. Rollback the changes\n\nDoing the rollback is almost the same as doing the migration, you just need to use `-b` option. Let's try to rollback the changes that we've done before but let's do it in dry run mode first.\n\n```\n$ ./shgrate -a mytestdb -b -r\nRollback 2016_04_05_21_06_20_create_table_user.sg_migrate.sql...done.\n\u003e\u003e Contents of file migrated/production/2016_04_05_21_06_20_create_table_user.sg_migrate.sql: \n-- shgrate Rollback Script\n-- Generated by: shgrate v1.0\n-- File: 2016_04_05_21_06_20_create_table_user.sg_migrate.sql\n-- Date: Tue, 05 Apr 2016 21:06:20 +0800\n-- Write your SQL rolllback migration below this line\nDROP TABLE user;\n```\n\nEverything seems as expected do the real rollback.\n\n```\n$ ./shgrate -a mytestdb -b\nRollback 2016_04_05_21_06_20_create_table_user.sg_migrate.sql...done.\n```\n\n## Advanced Usage\n\n### Debug Mode\n\nTo turn on debugging mode pass environment variable SG_DEBUG=true to shgrate. Output of the debug always saved to the log file also.\n\n```\n$ SG_DEBUG=true ./shgrate.sh -r -b -a shgrate\nDEBUG: Running in DRY RUN mode\nDEBUG: Using database name shgrate.\nDEBUG: Using MySQL client config file /home/astadev/.my.cnf.\nDEBUG: Migration directory is set to migrations.\nDEBUG: Migrated directory is set to migrated\nDEBUG: Rollback directory is set to rollback.\nDEBUG: Getting list of rollback files in migrated/production directory.\nRollback 2016_04_03_23_36_49_create_table_foo.sg_migrate.sql...done.\n\u003e\u003e Contents of file migrated/production/2016_04_03_23_36_49_create_table_foo.sg_migrate.sql: \n-- shgrate Rollback Script\n-- Generated by: shgrate v1.0\n-- File: 2016_04_03_23_36_49_create_table_foo.sg_migrate.sql\n-- Date: Sun, 03 Apr 2016 23:36:49 +0800\n-- Write your SQL rolllback migration below this line\nDROP TABLE foo;\n```\n\n### Using config file\n\nExample of a shgrate config file.\n```\n$ cat /home/user/conf/shgrate-dev.env.config\n# shgrate sample configuration file\n# ---------------------------------\n\n# Suffix migration for the shgrate\nSG_MIGRATE_SUFFIX=\"sg_dev.sql\"\n\n# Path to the log file\nSG_LOG_FILE=\"shgrate.log\"\n\n# Environment for production e.g: 'production', 'development', 'testing'\nSG_ENVIRONMENT=\"development\"\n\n# Name of the database\nSG_DB_NAME=\"testdb\"\n\n# MySQL client configuration file\n# Path to your main or custom ~/.my.cnf\nSG_MYSQL_CONFIG_FILE=\"~/.my.cnf\"\n\n# Migration directory\nSG_MIGRATION_DIR=\"/home/user/cool-project/migrations\"\n\n# Migrated directory\nSG_MIGRATED_DIR=\"/home/user/cool-project/migrated\"\n\n# Rollback directory\nSG_ROLLBACK_DIR=\"/home/user/cool-project/rollback\"\n```\n\nThen tells shgrate to use the config file instead.\n\n```\n$ ./shgrate -c /home/user/conf/shgrate-dev.env.config\n```\n\n## Author\n\nshgrate is written by Rio Astamal \u003cme@rioastamal.net\u003e\n\n## License\n\nshgrate is open source licensed under [MIT license](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frioastamal%2Fshgrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frioastamal%2Fshgrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frioastamal%2Fshgrate/lists"}