{"id":22525052,"url":"https://github.com/andrewpillar/mgrt","last_synced_at":"2025-08-03T21:32:08.806Z","repository":{"id":52144483,"uuid":"165134891","full_name":"andrewpillar/mgrt","owner":"andrewpillar","description":"Simple SQL migrations","archived":false,"fork":false,"pushed_at":"2023-11-05T12:55:28.000Z","size":173,"stargazers_count":25,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-06-19T04:24:12.511Z","etag":null,"topics":["go","migrations","sql-migration"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewpillar.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-10T21:40:01.000Z","updated_at":"2023-08-07T02:10:49.000Z","dependencies_parsed_at":"2022-09-05T02:42:06.655Z","dependency_job_id":"a3d49cd8-ac84-4ff1-8eb7-af0a6e17a884","html_url":"https://github.com/andrewpillar/mgrt","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewpillar%2Fmgrt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewpillar%2Fmgrt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewpillar%2Fmgrt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewpillar%2Fmgrt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewpillar","download_url":"https://codeload.github.com/andrewpillar/mgrt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228567027,"owners_count":17937986,"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":["go","migrations","sql-migration"],"created_at":"2024-12-07T06:08:05.886Z","updated_at":"2024-12-07T06:08:06.445Z","avatar_url":"https://github.com/andrewpillar.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mgrt\n\nmgrt is a simple tool for managing revisions across SQL databases. It takes SQL\nscripts, runs them against the database, and keeps a log of them.\n\n* [Quick start](#quick-start)\n* [Database connection](#database-connection)\n* [Revisions](#revisions)\n* [Categories](#categories)\n* [Revision log](#revision-log)\n* [Viewing revisions](#viewing-revisions)\n* [Library usage](#library-usage)\n\n## Quick start\n\nTo install mgrt, clone the repository and run the `./make.sh` script,\n\n    $ git clone https://github.com/andrewpillar/mgrt\n    $ cd mgrt\n    $ ./make.sh\n\nto build mgrt with SQLite3 support add `sqlite3` to the `TAGS` environment\nvariable,\n\n    $ TAGS=\"sqlite3\" ./make.sh\n\nthis will produce a binary at `bin/mgrt`, add this to your `PATH`.\n\nOnce installed you can start using mgrt right away, there is nothing to\ninitialize. To begin writing revisions simply invoke `mgrt add`,\n\n    $ mgrt add \"My first revision\"\n\nthis will create a new revision file in the `revisions` directory, and open\nit up for editting with the revision to write,\n\n    /*\n    Revision: 20060102150405\n    Author:   Andrew Pillar \u003cme@andrewpillar.com\u003e\n    \n    My first revision\n    */\n\n    CREATE TABLE users (\n        id INT NOT NULL UNIQUE\n    );\n\nonce you've saved the revision and quit the editor, you will see the revision ID\nprinted out,\n\n    $ mgrt add \"My first revision\"\n    revision created 20060102150405\n\nlocal revisions can be viewed with `mgrt ls`. This will display the ID, the\nauthor of the revision, and its comment, if any,\n\n    $ mgrt ls\n    20060102150405: Andrew Pillar \u003cme@andrewpillar.com\u003e - My first revision\n\nrevisions can be applied to the database via `mgrt run`. This command takes two\nflags, `-type` and `-dsn` to specify the type of database to run the revision\nagainst, and the data source for that database. Let's run our revision against\nan SQLite3 database,\n\n    $ mgrt run -type sqlite3 -dsn acme.db\n\nrevisions can only be performed on a database once, and cannot be undone. We can\nview the revisions that have been run against the database with `mgrt log`. Just\nlike `mgrt run`, we use the `-type` and `-dsn` flags to specify the database to\nconnect to,\n\n    $ mgrt log -type sqlite3 -dsn acme.db\n    revision 20060102150405\n    Author:    Andrew Pillar \u003cme@andrewpillar.com\u003e\n    Performed: Mon Jan  6 15:04:05 2006\n    My first revision\n    \n        CREATE TABLE users (\n            id INT NOT NULL UNIQUE\n        );\n\nthis will list out the revisions that have been performed, along with the SQL\ncode that was executed as part of that revision.\n\nmgrt also offers the ability to sync the revisions that have been performed on\na database against what you have locally. This is achieved with `mgrt sync`, and\njust like before, this also takes the `-type` and `-dsn` flags. Lets delete the\n`revisions` directory that was created for us and do a `mgrt sync`.\n\n    $ rm -rf revisions\n    $ mgrt ls\n    $ mgrt sync -type sqlite3 -dsn acme.db\n    $ mgrt ls\n    20060102150405: Andrew Pillar \u003cme@andrewpillar.com\u003e - My first revision\n\nwith `mgrt sync` you can easily view the revisions that have been run against\ndifferent databases.\n\n## Database connection\n\nDatabase connections for mgrt can be managed via the `mgrt db` command. This\nallows you to set aliases for the different databases you can connect to,\nfor example,\n\n    $ mgrt db set local-db postgresql \"host=localhost port=5432 dbname=dev user=admin password=secret\"\n\nthis can then be used via the `-db` flag for the commands that require a\ndatabase connection.\n\nThe `mgrt db set` command expects the type of the database, and the DSN for\nconnecting to the database. The type will be one of,\n\n* mysql\n* postgresql\n* sqlite3\n\nthe DSN will vary depending on the type of database being used. The mysql and\npostgresql you can use the URI connection string, such as,\n\n    type://[user[:password]@][host]:[port][,...][/dbname][?param1=value1\u0026...]\n\nwhere type would either be mysql or postgresql. The postgresql type also allows\nfor the DSN string such as,\n\n    host=localhost port=5432 dbname=mydb connect_timeout=10\n\nsqlite3 however will accept a filepath.\n\nYou can also specify the `-type` and `-dsn` flags too. These take the same\narguments as above. The `-db` flag however is more convenient to use.\n\n## Revisions\n\nRevisions are SQL scripts that are performed against the given database. Each\nrevision can only be performed once, and cannot be undone. If you wish to undo\na revision, then it is recommended to write another revision that does the\ninverse of the prior.\n\nRevisions are stored in the `revisions` directory from where the `mgrt add`\ncommand was run. Each revision file is prefixed with a comment block header\nthat contains metadata about the revision itself, such as the ID, the author and\na short comment about the revision.\n\n## Categories\n\nRevisions can be organized into categories via the command line. This is done\nby passing the `-c` flag to the `mgrt add` command and specifying the category\nfor that revision. This will create a sub-directory in the `revisions` directory\ncontaining that revision. Revisions in a category will only be performed when\nthe `-c` flag for that category is given to the `mgrt run` command.\n\nOrganizing revisions into categories can be useful if you want to keep certain\nrevision logic separate from other revision logic. For example, if you want to\nseparate table creation from permission granting, you could do something like,\n\n    $ mgrt add -c schema \"Create users table\"\n    $ mgrt add -c perms \"Grant permissions on users table\"\n\nthen, to perform the above revisions you would,\n\n    $ mgrt run -c schema -db prod\n    $ mgrt run -c perms -db prod\n\n## Revision log\n\nEach time a revision is performed, a log will be made of that revision. This log\nis stored in the database, in the `mgrt_revisions` table. This will contain the\nID, the author, the comment (if any), and the SQL code itself, along with the\ntime of execution.\n\nThe revisions performed against a database can be viewed with `mgrt log`,\n\n    $ mgrt log -db local-dev\n    revision 20060102150405\n    Author:    Andrew Pillar \u003cme@andrewpillar.com\u003e\n    Performed: Mon Jan  6 15:04:05 2006\n\n        My first revision\n\n## Viewing revisions\n\nLocal revisions can be viewed with `mgrt cat`. This simply takes a list of\nrevision IDs to view.\n\n    $ mgrt cat 20060102150405\n    /*\n    Revision: 20060102150405\n    Author:   Andrew Pillar \u003cme@andrewpillar.com\u003e\n    \n    My first revision\n    */\n    \n    CREATE TABLE users (\n            id INT NOT NULL UNIQUE\n    );\n\nThe `-sql` flag can be passed to the command too to only display the SQL portion\nof the revision,\n\n    $ mgrt cat -sql 20060102150405\n    CREATE TABLE users (\n            id INT NOT NULL UNIQUE\n    );\n\nperformed revisions can also be seen with `mgrt show`. You can pass a revision\nID to `mgrt show` to view an individual revision. If no revision ID is given,\nthen the latest revision is shown.\n\n    $ mgrt show -db local-dev 20060102150405\n    revision 20060102150405\n    Author:    Andrew Pillar \u003cme@andrewpillar.com\u003e\n    Performed: Mon Jan  6 15:04:05 2006\n\n        My first revision\n\n        CREATE TABLE users (\n                id INT NOT NULL UNIQUE\n        );\n\n## Library usage\n\nAs well as a CLI application, mgrt can be used as a library should you want to\nbe able to have revisions performed directly in your application. To start using\nit just import the repository into your code,\n\n    import \"github.com/andrewpillar/mgrt\"\n\nfrom here you will be able to start creating revisions and performing them\nagainst any pre-existing database connection you may have,\n\n    // mgrt.Open will wrap sql.Open from the stdlib, and initialize the database\n    // for performing revisions.\n    db, err := mgrt.Open(\"sqlite3\", \"acme.db\")\n\n    if err != nil {\n        panic(err) // maybe acceptable here\n    }\n\n    rev := mgrt.NewRevision(\"Andrew\", \"This is being done from Go.\")\n\n    if err := rev.Perform(db); err != nil {\n        if !errors.Is(err, mgrt.ErrPerformed) {\n            panic(err) // not best practice\n        }\n    }\n\nall pre-existing revisions can be retrieved via GetRevisions,\n\n    revs, err := mgrt.GetRevisions(db)\n\n    if err != nil {\n        panic(err) // don't actually do this\n    }\n\nmore information about using mgrt as a library can be found in the\n[Go doc](https://pkg.go.dev/github.com/andrewpillar/mgrt) itself for mgrt.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewpillar%2Fmgrt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewpillar%2Fmgrt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewpillar%2Fmgrt/lists"}